From a8c8036f49c7164f4e95ff14b33668b157a5ddfe Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 12 Oct 2026 17:39:13 -0500
Subject: [PATCH 001/109] Record actions in a document-independent form (#219)

Journal entries are what Actions record, so a step must mean the same
thing on another document. The UI names the layer it clicked by id,
which only replays on the document the recording came from.

Before an entry is journaled (actions_record.rs):
- a `layer` id that was the active (and only selected) layer is dropped,
  so the step acts on the active layer when played;
- any other id becomes the layer's name when unique in the document
  (`layer.select` always, like Photoshop's "Select layer"); an
  ambiguous name keeps the id;
- Type tool keystrokes (`type.edit` with `replace` and the session's
  `coalesce` key) fold into the `type.create` that made the layer or
  into one `type.edit` with the whole text, as Photoshop records "Make
  text layer" and "Set current text layer".

The dispatcher captures the document before the command, also for
background jobs, and remembers which text layer the last entry typed
into, since the Type tool selects a clicked layer without a command.

Tests: 11 in actions_record/tests.rs, including a recording that
replays on a document whose layers have other ids. Scorecard
AUTO-219-1 done; gaps, parity and protocol docs updated.
---
 crates/engine/src/actions_record.rs       | 128 +++++++++++++++
 crates/engine/src/actions_record/tests.rs | 184 ++++++++++++++++++++++
 crates/engine/src/jobs.rs                 |  29 +++-
 crates/engine/src/lib.rs                  |   3 +
 docs/control-protocol.md                  |   2 +-
 docs/gaps.md                              |   9 +-
 docs/scorecard.md                         |   4 +-
 docs/target-app-parity.md                 |   3 +-
 scorecard/automation.toml                 |   4 +-
 9 files changed, 352 insertions(+), 14 deletions(-)
 create mode 100644 crates/engine/src/actions_record.rs
 create mode 100644 crates/engine/src/actions_record/tests.rs

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
new file mode 100644
index 0000000000..5c43797271
--- /dev/null
+++ b/crates/engine/src/actions_record.rs
@@ -0,0 +1,128 @@
+//! Document-independent recording (#219).
+//!
+//! The journal is what Actions record, so an entry must mean the same thing on another document.
+//! The UI names the layer it clicked by id (`"layer": 7`); ids are per document, so a step kept
+//! that way replays only on the document it came from. Before an entry is journaled:
+//!
+//! - a `layer` that was the active (and only selected) layer when the command ran is dropped:
+//!   the step acts on the active layer, as Photoshop's "current layer" does;
+//! - any other `layer` id becomes the layer's name when the name is unique in the document, and
+//!   `layer.select` always does (selecting is choosing a layer by name, as Photoshop records
+//!   it); an ambiguous name keeps the id, which still replays on the recording document;
+//! - the Type tool's keystrokes (`type.edit` with `replace` and the editing session's `coalesce`
+//!   key) fold into the entry before them: the `type.create` that made the layer gets the final
+//!   text, and keystrokes in an existing layer become one `type.edit` with the whole text, as
+//!   Photoshop records "Make text layer" and "Set current text layer".
+//!
+//! Ids are still accepted everywhere; only what the journal keeps changes.
+
+use std::sync::Arc;
+
+use photocraft_doc::{Document, LayerContent, LayerId};
+use serde_json::Value;
+
+use crate::Session;
+
+/// The active document as it was before a command ran, captured by the dispatcher.
+#[derive(Clone, Default)]
+pub(crate) struct Before {
+    doc: Option<Arc<Document>>,
+    active_layer: Option<LayerId>,
+    /// Every selected layer: a `layer` that is one of several stays explicit, because without it
+    /// a layer command acts on the whole selection ([`crate::layer_multi_cmds::targets`]).
+    selected: Vec<LayerId>,
+}
+
+impl Before {
+    pub(crate) fn capture(s: &Session) -> Self {
+        match s.active() {
+            Some(st) => Self { doc: Some(st.doc.clone()), active_layer: st.active_layer, selected: st.selected_layers() },
+            None => Self::default(),
+        }
+    }
+}
+
+/// `params` with its `layer` id made portable (see the module doc).
+pub(crate) fn portable(id: &str, mut params: Value, before: &Before) -> Value {
+    let Some(doc) = before.doc.as_deref() else { return params };
+    let Some(target) = params.get("layer").and_then(Value::as_u64).map(LayerId) else { return params };
+    let Some(obj) = params.as_object_mut() else { return params };
+    let only_selected = before.selected.len() <= 1;
+    if id != "layer.select" && before.active_layer == Some(target) && only_selected {
+        obj.remove("layer");
+        return params;
+    }
+    if let Some(layer) = doc.layer(target)
+        && doc.walk().iter().filter(|(_, _, l)| l.name == layer.name).count() == 1
+    {
+        obj.insert("layer".into(), Value::String(layer.name.clone()));
+    }
+    params
+}
+
+/// The text layer a journaled `type.create` made or `type.edit` changed, so the keystrokes that
+/// follow fold into that entry only when they type into the same layer (the Type tool selects
+/// a clicked layer without a command, so the journal alone cannot tell).
+pub(crate) fn typed_layer(s: &Session, id: &str, params: &Value) -> Option<LayerId> {
+    match id {
+        "type.create" => s.active()?.active_layer,
+        "type.edit" => crate::commands::layer_param(s, params).ok(),
+        _ => None,
+    }
+}
+
+/// What the journal keeps of a Type-tool keystroke.
+pub(crate) enum Keystroke {
+    /// Not a keystroke: the entry is journaled as it is.
+    None,
+    /// Folded into the entry before it.
+    Folded,
+    /// A new entry setting the whole text, so a later keystroke can fold into it.
+    Step(Value),
+}
+
+/// Folds a Type-tool keystroke into the journal entry before it (see the module doc), or turns
+/// it into a whole-text step. `previous` is the layer the last entry typed into.
+pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous: Option<LayerId>) -> Keystroke {
+    if id != "type.edit" {
+        return Keystroke::None;
+    }
+    let Some(obj) = params.as_object() else { return Keystroke::None };
+    let Some(key) = obj.get("coalesce").and_then(Value::as_str) else { return Keystroke::None };
+    if !obj.contains_key("replace") || !obj.keys().all(|k| matches!(k.as_str(), "layer" | "replace" | "coalesce")) {
+        return Keystroke::None;
+    }
+    let Ok(target) = crate::commands::layer_param(s, params) else { return Keystroke::None };
+    // The text as it is now, after this keystroke: the step sets it whole.
+    let Some(text) = s.active().and_then(|st| st.doc.layer(target)).and_then(|l| match &l.content {
+        LayerContent::Text(t) => Some(t.text.clone()),
+        _ => None,
+    }) else {
+        return Keystroke::None;
+    };
+    let layer = obj.get("layer");
+    let whole = || {
+        let mut step = obj.clone();
+        step.remove("replace");
+        step.insert("text".into(), Value::String(text.clone()));
+        Keystroke::Step(Value::Object(step))
+    };
+    if previous != Some(target) {
+        return whole();
+    }
+    let Some((last, lp)) = s.journal.last_mut() else { return whole() };
+    let Some(lo) = lp.as_object_mut() else { return whole() };
+    let folds = match last.as_str() {
+        "type.create" => layer.is_none(),
+        "type.edit" => lo.get("coalesce").and_then(Value::as_str) == Some(key) && lo.get("layer") == layer && lo.contains_key("text"),
+        _ => false,
+    };
+    if !folds {
+        return whole();
+    }
+    lo.insert("text".into(), Value::String(text));
+    Keystroke::Folded
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
new file mode 100644
index 0000000000..2da6e21401
--- /dev/null
+++ b/crates/engine/src/actions_record/tests.rs
@@ -0,0 +1,184 @@
+use photocraft_doc::LayerId;
+use serde_json::{Value, json};
+
+use crate::jobs::Started;
+use crate::{EngineError, Session};
+
+fn session() -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 32, "height": 32, "background": "white"})).unwrap();
+    s
+}
+
+fn new_layer(s: &mut Session, name: &str) -> u64 {
+    s.execute("layer.new.layer", json!({"name": name})).unwrap()["layer"].as_u64().unwrap()
+}
+
+fn last(s: &Session) -> &(String, Value) {
+    s.journal.last().unwrap()
+}
+
+fn background(s: &Session) -> u64 {
+    s.active().unwrap().doc.layers[0].id.0
+}
+
+#[test]
+fn the_active_layer_is_implicit() {
+    let mut s = session();
+    let shade = new_layer(&mut s, "Shade");
+    s.execute("layer.setProps", json!({"layer": shade, "opacity": 0.5})).unwrap();
+    assert_eq!(last(&s), &("layer.setProps".into(), json!({"opacity": 0.5})), "the active layer's id is dropped");
+    assert_eq!(s.active().unwrap().doc.layer(LayerId(shade)).unwrap().opacity, 0.5, "the command still ran on it");
+}
+
+#[test]
+fn another_layer_is_named() {
+    let mut s = session();
+    let bg = background(&s);
+    new_layer(&mut s, "Shade");
+    s.execute("layer.setProps", json!({"layer": bg, "visible": false})).unwrap();
+    assert_eq!(last(&s), &("layer.setProps".into(), json!({"layer": "Background", "visible": false})));
+}
+
+#[test]
+fn selecting_a_layer_is_always_by_name() {
+    let mut s = session();
+    let shade = new_layer(&mut s, "Shade");
+    s.execute("layer.select", json!({"layer": shade})).unwrap();
+    assert_eq!(last(&s), &("layer.select".into(), json!({"layer": "Shade"})), "even though it was the active layer");
+    s.execute("layer.select", json!({"layer": shade, "mode": "toggle"})).unwrap();
+    assert_eq!(last(&s).1["mode"], "toggle", "the other params are kept");
+}
+
+#[test]
+fn an_ambiguous_name_keeps_the_id() {
+    let mut s = session();
+    let a = new_layer(&mut s, "Copy");
+    let b = new_layer(&mut s, "Copy");
+    s.execute("layer.setProps", json!({"layer": a, "opacity": 0.5})).unwrap();
+    assert_eq!(last(&s), &("layer.setProps".into(), json!({"layer": a, "opacity": 0.5})), "two layers are called Copy");
+    s.execute("layer.setProps", json!({"layer": b, "opacity": 0.5})).unwrap();
+    assert_eq!(last(&s).1, json!({"opacity": 0.5}), "the active one is still implicit");
+}
+
+#[test]
+fn one_of_several_selected_layers_stays_named() {
+    let mut s = session();
+    let bg = background(&s);
+    let shade = new_layer(&mut s, "Shade");
+    s.execute("layer.select", json!({"layer": bg, "mode": "add"})).unwrap();
+    assert_eq!(s.active().unwrap().selected_layers().len(), 2);
+    let active = s.active().unwrap().active_layer.unwrap().0;
+    let name = if active == shade { "Shade" } else { "Background" };
+    s.execute("layer.setProps", json!({"layer": active, "opacity": 0.5})).unwrap();
+    assert_eq!(last(&s).1, json!({"layer": name, "opacity": 0.5}), "without the layer, a layer command acts on the whole selection");
+}
+
+#[test]
+fn a_name_or_no_document_is_left_alone() {
+    let mut s = session();
+    new_layer(&mut s, "Shade");
+    s.execute("layer.setProps", json!({"layer": "Background", "visible": false})).unwrap();
+    assert_eq!(last(&s).1, json!({"layer": "Background", "visible": false}));
+    let e = s.execute("layer.setProps", json!({"layer": 999, "visible": false})).unwrap_err();
+    assert!(matches!(e, EngineError::NoLayer(_)), "{e}");
+}
+
+#[test]
+fn a_background_job_journals_the_same_way() {
+    let mut s = session();
+    let shade = new_layer(&mut s, "Shade");
+    let id = match s.start("filter.blur.gaussianBlur", json!({"layer": shade, "radius": 2})).unwrap() {
+        Started::Job(id) => id,
+        Started::Done(v) => panic!("ran inline: {v}"),
+    };
+    s.wait_job(id).unwrap();
+    assert_eq!(last(&s), &("filter.blur.gaussianBlur".into(), json!({"radius": 2})));
+}
+
+#[test]
+fn keystrokes_fold_into_the_type_layer_they_made() {
+    let mut s = session();
+    let id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let n = s.journal.len();
+    for (i, ch) in "Hey".chars().enumerate() {
+        s.execute("type.edit", json!({"layer": id, "replace": {"start": i, "end": i, "text": ch.to_string()}, "coalesce": "t1"})).unwrap();
+    }
+    // Backspace, then more.
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 2, "end": 3, "text": ""}, "coalesce": "t1"})).unwrap();
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 2, "end": 2, "text": "llo"}, "coalesce": "t1"})).unwrap();
+    assert_eq!(s.journal.len(), n, "every keystroke folded into Make Type Layer");
+    let (cmd, p) = last(&s);
+    assert_eq!(cmd, "type.create");
+    assert_eq!(p["text"], "Hello");
+    assert!(p.get("replace").is_none() && p.get("coalesce").is_none(), "{p}");
+}
+
+#[test]
+fn keystrokes_in_an_existing_layer_become_one_edit() {
+    let mut s = session();
+    let id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "Hi", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    s.execute("layer.setProps", json!({"opacity": 0.9})).unwrap();
+    let n = s.journal.len();
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 2, "end": 2, "text": "!"}, "coalesce": "t2"})).unwrap();
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 0, "end": 1, "text": "h"}, "coalesce": "t2"})).unwrap();
+    assert_eq!(s.journal.len(), n + 1);
+    assert_eq!(last(&s), &("type.edit".into(), json!({"text": "hi!", "coalesce": "t2"})));
+    // A new editing session starts a new step.
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 3, "end": 3, "text": "?"}, "coalesce": "t3"})).unwrap();
+    assert_eq!(s.journal.len(), n + 2);
+    assert_eq!(last(&s).1, json!({"text": "hi!?", "coalesce": "t3"}));
+}
+
+#[test]
+fn keystrokes_into_another_layer_do_not_fold() {
+    let mut s = session();
+    let first = s.execute("type.create", json!({"x": 2, "y": 10, "text": "One", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let second = s.execute("type.create", json!({"x": 2, "y": 20, "text": "", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    // The Type tool selects a clicked layer without a command.
+    s.select_layer(LayerId(first)).unwrap();
+    let n = s.journal.len();
+    s.execute("type.edit", json!({"layer": first, "replace": {"start": 3, "end": 3, "text": "!"}, "coalesce": "t4"})).unwrap();
+    assert_eq!(s.journal.len(), n + 1, "typing into the first layer is its own step");
+    assert_eq!(last(&s).1, json!({"text": "One!", "coalesce": "t4"}));
+    assert_eq!(s.journal[n - 1].1["text"], "", "the second Make Type Layer keeps its own text");
+    // Programmatic edits (no session key) and other edits stand on their own.
+    s.execute("type.edit", json!({"layer": second, "replace": {"start": 0, "end": 0, "text": "x"}})).unwrap();
+    assert!(last(&s).1["layer"].is_string() && last(&s).1.get("replace").is_some(), "{}", last(&s).1);
+}
+
+#[test]
+fn a_recording_replays_on_a_document_with_other_layer_ids() {
+    let mut s = session();
+    let bg = background(&s);
+    s.execute("actions.record", json!({"name": "Shade"})).unwrap();
+    let shade = new_layer(&mut s, "Shade");
+    s.execute("layer.setProps", json!({"layer": shade, "opacity": 0.5})).unwrap();
+    s.execute("layer.select", json!({"layer": bg})).unwrap();
+    s.execute("edit.fill", json!({"layer": bg, "color": "#ff0000"})).unwrap();
+    let id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    for (i, ch) in "Hi".chars().enumerate() {
+        s.execute("type.edit", json!({"layer": id, "replace": {"start": i, "end": i, "text": ch.to_string()}, "coalesce": "t5"})).unwrap();
+    }
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Shade"})).unwrap()["steps"].clone();
+    let ids: Vec<&str> = steps.as_array().unwrap().iter().map(|st| st[0].as_str().unwrap()).collect();
+    assert_eq!(ids, ["layer.new.layer", "layer.setProps", "layer.select", "edit.fill", "type.create"], "{steps}");
+    assert!(steps.as_array().unwrap().iter().all(|st| st[1].get("layer").is_none_or(Value::is_string)), "no layer ids: {steps}");
+
+    // A second document whose layers have other ids and a layer stacked over the background.
+    s.execute("file.new", json!({"width": 40, "height": 40, "background": "black"})).unwrap();
+    new_layer(&mut s, "Top");
+    assert_ne!(background(&s), bg);
+    let played = s.execute("actions.play", json!({"action": "Shade"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    let d = &s.active().unwrap().doc;
+    let shade = d.walk().into_iter().find(|(_, _, l)| l.name == "Shade").map(|(_, _, l)| l).unwrap();
+    assert_eq!(shade.opacity, 0.5, "the new layer, not the one of the first document, got the opacity");
+    let text = d.walk().into_iter().find_map(|(_, _, l)| match &l.content {
+        photocraft_doc::LayerContent::Text(t) => Some(t.text.clone()),
+        _ => None,
+    });
+    assert_eq!(text.as_deref(), Some("Hi"), "the typed text replayed as one step");
+    assert!(s.documents()[0].doc.layer(LayerId(bg)).is_some());
+}
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index 9c8cb9cdd0..7e839ec436 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -182,6 +182,8 @@ struct Running {
     started_ms: f64,
     coalesce: Option<String>,
     color_restrict: Option<usize>,
+    /// The document before the command, for document-independent journaling.
+    before: crate::actions_record::Before,
     rx: std::sync::mpsc::Receiver<Result<Payload>>,
     apply: Option<Apply>,
     #[cfg(not(target_arch = "wasm32"))]
@@ -335,6 +337,7 @@ pub fn run<T: Send + 'static>(
         started_ms: now_ms(),
         coalesce: s.coalesce_request.clone(),
         color_restrict: s.color_restrict,
+        before: crate::actions_record::Before::capture(s),
         rx,
         apply: Some(erased),
         #[cfg(not(target_arch = "wasm32"))]
@@ -659,6 +662,7 @@ impl Session {
         // action it plays (a script step) must not flush the steps it ran so far into the action
         // being recorded, nor move the recording mark past the entries it is about to replace.
         let recording = if spec.journal && crate::actions_cmds::replayable(id) { self.actions.recording.take() } else { None };
+        let before = crate::actions_record::Before::capture(self);
         // Last-resort guard (AGENTS.md, Never crash): a command that panics anyway fails with an
         // error instead of taking the app down. `edit` only commits a document after its closure
         // returns, so the documents are unchanged.
@@ -686,7 +690,7 @@ impl Session {
                 Ok(Started::Job(jid))
             }
             (Ok(v), None) => {
-                self.after_command(id, params, spec.journal, Some(nested_from));
+                self.after_command(id, params, spec.journal, Some(nested_from), &before);
                 Ok(Started::Done(v))
             }
         }
@@ -699,7 +703,11 @@ impl Session {
     /// dropped, so a recorded action replays the command once, not its steps as well (#3067).
     /// Edit › Transform › Again (and Again on a Copy) is not replayable and keeps the concrete
     /// steps it ran instead.
-    fn after_command(&mut self, id: &str, params: Value, journal: bool, nested_from: Option<usize>) {
+    ///
+    /// `before` is the active document before the command: the journal names layers as the
+    /// command's caller saw them, in a form that replays on another document
+    /// ([`crate::actions_record`]).
+    fn after_command(&mut self, id: &str, params: Value, journal: bool, nested_from: Option<usize>, before: &crate::actions_record::Before) {
         // A layer-mask view ends when another layer becomes active (#196).
         if let Some(st) = self.active_mut() {
             crate::mask_view_cmds::fix(st);
@@ -713,9 +721,18 @@ impl Session {
         if let Some(from) = nested_from.filter(|_| crate::actions_cmds::replayable(id)) {
             self.journal.truncate(from);
         }
-        if !crate::brush_cmds::coalesce_journal(self, id, &params) {
-            self.journal.push((id.to_string(), params));
+        let typed = crate::actions_record::typed_layer(self, id, &params);
+        let params = crate::actions_record::portable(id, params, before);
+        match crate::actions_record::fold_keystroke(self, id, &params, self.typed_layer) {
+            crate::actions_record::Keystroke::Folded => {}
+            crate::actions_record::Keystroke::Step(step) => self.journal.push((id.to_string(), step)),
+            crate::actions_record::Keystroke::None => {
+                if !crate::brush_cmds::coalesce_journal(self, id, &params) {
+                    self.journal.push((id.to_string(), params));
+                }
+            }
         }
+        self.typed_layer = typed;
     }
 
     /// Apply (or report the failure of) a job whose worker has delivered `r`.
@@ -735,7 +752,7 @@ impl Session {
     }
 
     fn apply_job(&mut self, job: &Running, apply: Option<Apply>, payload: Payload) -> Result<Value> {
-        let Running { label, doc, snapshot, coalesce, color_restrict, command, params, journal, .. } = job;
+        let Running { label, doc, snapshot, coalesce, color_restrict, command, params, journal, before, .. } = job;
         let prev_active = self.active;
         let target = match doc {
             Some(d) => {
@@ -770,7 +787,7 @@ impl Session {
         // Restoring the viewed document first would attribute Fade and slice updates
         // to that document instead, when the user switched tabs mid-job.
         if r.is_ok() {
-            self.after_command(command, params.clone(), *journal, Some(nested_from));
+            self.after_command(command, params.clone(), *journal, Some(nested_from), before);
         }
         // Keep the user's active document unless the job opened a new one.
         // This also restores the selection when the apply step returned an error.
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 58a8974298..495d9a7fdf 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -9,6 +9,7 @@
 
 pub mod actions_cmds;
 pub mod actions_edit_cmds;
+pub mod actions_record;
 pub mod adjust_cmds;
 pub mod adjust_params;
 pub mod align_cmds;
@@ -377,6 +378,8 @@ pub struct Session {
     pub journal: Vec<(String, Value)>,
     /// Coalescing key of the command being executed.
     coalesce_request: Option<String>,
+    /// The text layer the last journal entry made or typed into ([`actions_record`]).
+    typed_layer: Option<LayerId>,
     /// Pixels copied with Edit › Copy / Cut (shared by all documents, like Photoshop).
     pub clipboard: Option<edit_cmds::Clip>,
     /// Layer › Layer Style › Copy Layer Style: effects, blend mode, fill opacity and the Advanced
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index e571e94f8b..c39ff69f8e 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -123,7 +123,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted) |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). Steps are document-independent: a `layer` id that was the active layer is dropped (the step acts on the active layer when played), any other layer is recorded by name when the name is unique in the document (`layer.select` always), and the Type tool's keystrokes fold into one `type.create`/`type.edit` step carrying the whole text |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |
diff --git a/docs/gaps.md b/docs/gaps.md
index 23b3751235..af365f972e 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -1,6 +1,6 @@
 # Where PhotoCraft falls short of Photoshop
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-13 · **Change:** minor (G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-13 · **Change:** minor (G11: document-independent recording landed, AUTO-219-1 done; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed) · **Target:** Adobe Photoshop 2026
 
 Every known shortfall against Photoshop 2026 (27.11.0), one entry each, ranked by user impact
 on the way to beta. This is the work list agents pick from: take the highest-ranked entry that
@@ -88,7 +88,7 @@ what an agent can't finish alone.
 - **Estimate:** 120–200 h.
 
 ### G11. Actions and scripting
-- **Missing:** document-independent action recording (AUTO-219-1), Batch recursion and naming
+- **Missing:** Batch recursion and naming
   (AUTO-219-5), ExtendScript/UXP compatibility. `.atn` steps outside the
   mapped events (paths, scripts, Generative Fill, Filter Gallery effects other than Spatter,
   Duplicate Layers into a new document, Bitmap halftone screens…) load as kept Photoshop steps
@@ -111,6 +111,10 @@ what an agent can't finish alone.
   in set folders, has the dialog toggle column (playback pauses on the step's dialog and resumes
   on OK) and Insert Stop…; `actions.insert`, `actions.dialog`, `actions.assignSet` for agents
   (AUTO-219-2 done).
+- **Done 2026-10-12:** recording is document-independent (AUTO-219-1): a step on the active
+  layer records no layer, any other layer records by name (Select Layer always), and the Type
+  tool's keystrokes fold into one Make Type Layer / Edit Type step with the whole text, as
+  Photoshop records them; a recording replays on a document whose layers have other ids.
 - **Ahead of Photoshop:** CLI, MCP and the JSON control channel drive every command.
 - **Estimate:** 120–200 h. **Human:** whether to support a JavaScript scripting dialect at all
   (AGENTS.md forbids JS in the app).
@@ -266,6 +270,7 @@ what an agent can't finish alone.
 | 2026-10-12 | minor | G4: checkbox-only Brush Settings rows preserve the open controls and Smoothing settings (#4283); no readiness percentage or estimate changed |
 | 2026-10-12 | minor | G11: Load/Save Actions `.atn` landed (AUTO-219-2 partial); remaining panel work listed |
 | 2026-10-12 | minor | Refreshed against main: G5 items fixed by #2480, #2327, #2609, #2684, #2675, #2556, #2396, #2527, #2625 and TOOL-214-5/#2442; G7 TOOL-214-7 and Transform On Drop done; G2 #2377 fixed (#2417); G9 UI scale (UI-217-9) and Stamp Visible (UI-217-22) done, prefs 27 of 156; G10 #2225 done (#2482); G13 Khmer, Lao, Myanmar fallback (#3259); G14 CR3 line; G17 Windows ARM64 done (DIST-220-2) |
+| 2026-10-12 | minor | G11: document-independent recording landed (AUTO-219-1 done) |
 | 2026-10-11 | minor | D5100 image area and Camera Raw tuning validation; G14 remains open |
 | 2026-10-11 | minor | G13: Czech dynamic UI text localized; engine messages and native review remain open |
 | 2026-10-11 | minor | G8: triple/quadruple/five-click type selection done (TYPE-218-8, #3493); Type evidence recounted |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index 1ad3f3aa3d..369137da50 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -11,7 +11,7 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
 | [Tools](#tools) | 28 | 14 | 1 |  |
 | [Workspace and UI](#workspace-and-ui) | 13 | 6 | 4 | settings that do nothing: 26 of 156 (target 0) |
 | [Type](#type) | 4 | 3 | 2 |  |
-| [Automation](#automation) | 5 | 2 | 4 | 631 of 631 menu items live (100.0%) |
+| [Automation](#automation) | 6 | 2 | 3 | 631 of 631 menu items live (100.0%) |
 | [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 28 of 28 crates; panic_hunt present |
 | [Distribution](#distribution) | 5 | 4 | 2 |  |
 | [Open bugs](#open-bugs) | 29 | 2 | 1 |  |
@@ -227,7 +227,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | Id | Target | Status | Issue | Note |
 |---|---|---|---|---|
 | AUTO-1 | Every menu item dispatches a command id (UI, CLI, control channel and MCP share them) | done |  | docs/parity-checklist.md: all menu items live; menus.rs is_live |
-| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | missing | [#219](https://github.com/storytold/photocraft/issues/219) | actions.rs:47 copies raw journal entries with explicit layer ids |
+| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_record.rs: the active layer's id is dropped, other layers are journaled by name (layer.select always), Type tool keystrokes fold into one type.create/type.edit with the whole text; replay test on a document with other layer ids |
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index f6209c58db..b09372edd4 100644
--- a/docs/target-app-parity.md
+++ b/docs/target-app-parity.md
@@ -177,7 +177,7 @@ parity for the area and are already contained in the dimension rows above.
 | Vector shapes and paths | 55% | 80–140 | Pen, Direct/Path Selection, shapes, shape strokes. Freeform and Curvature Pen (#1054). Add/Delete Anchor Point and Convert Point tools exist (`Tool` enum); missing on-canvas corner radius (TOOL-214-12), path-point nudge; shape parity tracking issue #2496 |
 | Colour management and modes | 70% | 60–100 | Own ICC engine, soft proof, CMYK/Lab/Indexed/Duotone/Multichannel; no Adobe CMYK profiles, no spot plates (FILE-215-17), monitor profile only at launch |
 | Camera Raw and computational photo (Photomerge, HDR, lens) | 45% | 120–200 | Raw for DNG/CR2/NEF/ARW/RW2/ORF/RAF(uncompressed)/PEF; no CR3; ACR dialog partial (no masking, calibration); generic lens profiles only |
-| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; Actions panel and recording not document-independent (AUTO-219-1/2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); no ExtendScript/UXP |
+| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; recording document-independent and the panel complete since 2026-10-12 (AUTO-219-1/2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); no ExtendScript/UXP |
 | File I/O | 60% | 300–500 | See [file-format-parity.md](file-format-parity.md) |
 | Print, export, Save for Web | 50% | 60–100 | JPEG Options dialog missing (FILE-215-19), no Photoshop PDF, no separations, Save for Web settings not remembered |
 | Video / timeline, data-driven graphics | 30% | 100–200 | Menu items live; frame model persists in `.pcraft`; no PSD video-layer mapping |
@@ -567,6 +567,7 @@ See [method, raw measurements and reproduction](five-algorithm-performance.md).
 | 2026-10-12 | minor | `.atn` import: 112 events mapped (TrueGrit Texture Supply sets play end to end); percentages unchanged |
 | 2026-10-12 | minor | Photoshop Actions `.atn` load and save (90 events mapped both ways); percentages unchanged |
 | 2026-10-12 | minor | Rows checked against `main` and the regenerated scorecard: menu count 631, Workspace checklist and preference count, transform context menu, Puppet Warp mesh, Select and Mask, anchor-point tools, Smart Object conversion, Stamp Visible, mask targeting, Free Transform commit/cancel, Vietnamese catalog, Windows ARM64; percentages, weights and hours not re-measured |
+| 2026-10-12 | minor | Document-independent action recording (AUTO-219-1); percentages unchanged |
 | 2026-10-10 | minor | Added measured Tilt-Shift computation/filtered-proxy gains and inconclusive cases; parity percentages and budgets unchanged |
 | 2026-10-10 | minor | Readiness-by-audience table: percent and hours for full, mainstream and essentials; full number confirmed as the additive weighted sum over dimensions (46%, reported ~45%) |
 | 2026-10-10 | minor | Added mainstream-practitioner (~43%) and essentials-user (~61%) numbers with written weights and discounts; full ready-for-real-work rechecked against its written weights (46%, reported ~45%), unchanged |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index 0de2ab3bd2..5ae52f6d32 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -14,9 +14,9 @@ note = "docs/parity-checklist.md: all menu items live; menus.rs is_live"
 [[item]]
 id = "AUTO-219-1"
 target = "Record actions in a document-independent form (implicit layer, merged type keystrokes)"
-status = "missing"
+status = "done"
 issue = 219
-note = "actions.rs:47 copies raw journal entries with explicit layer ids"
+note = "actions_record.rs: the active layer's id is dropped, other layers are journaled by name (layer.select always), Type tool keystrokes fold into one type.create/type.edit with the whole text; replay test on a document with other layer ids"
 
 [[item]]
 id = "AUTO-219-2"

From bc08629d292e1383a41e0db254a00a907f42c9e2 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 12 Oct 2026 18:35:48 -0500
Subject: [PATCH 002/109] Batch: subfolders, open documents, file naming, stop
 on error, error log, progress and cancel (#219)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

File › Automate › Batch now covers Photoshop's dialog (AUTO-219-5):

- Source: a folder with Include All Subfolders (the output mirrors the
  folder tree, so same-named files in different subfolders don't
  collide), or the open documents (`"source": "open"`: the steps run on
  every open document as history steps; with an output folder a copy of
  each is saved there).
- File Naming: a template with Photoshop's fields as tokens: {name}
  {NAME} {Name}, {serial} to {serial:4} from startSerial, {letter}
  {LETTER}, {date:mmddyy|mmdd|yyyymmdd|yymmdd|yyddmm|ddmmyy}, {ext}
  {EXT}, other text literal. Default {name}.{ext}, the old naming.
- Errors: stopOnError stops at the first failing file and reports the
  skipped ones; errorLog writes the failures to a text file.
- The command runs as a job: the status bar shows "n of total: file"
  and Cancel stops after the current file.

The options live in the new engine module `batch` and are shared by
Image Processor, the Lens Correction batch and the CLI's `batch`
(--recursive --naming --start-serial --stop-on-error --error-log).
The generic form dialog takes an `__order` hint so the Batch dialog is
grouped as Photoshop's (Play, Source, Destination, Errors). chrono
(clock, native only) supplies the local date for the date tokens.

Tests: 9 in batch/tests.rs (tokens and rejected templates, recursive
listing, mirrored output, stop/skip/log, cancelled context, background
job, open-documents source), one CLI test, one form-order test. The
batch_export_options helpers pick the nearest field on a label's row,
since the taller dialog's Quality row now shares a height with the
Layers panel's opacity field. Scorecard AUTO-219-5 done; gaps, parity
and development docs updated.
---
 Cargo.lock                                   |   1 +
 apps/photocraft-cli/src/lib.rs               | 146 +++++++-
 crates/engine/Cargo.toml                     |   2 +
 crates/engine/src/batch.rs                   | 338 +++++++++++++++++++
 crates/engine/src/batch/tests.rs             | 248 ++++++++++++++
 crates/engine/src/file_cmds.rs               | 213 ++++++++++--
 crates/engine/src/lens_cmds.rs               |   8 +-
 crates/engine/src/lib.rs                     |   1 +
 crates/ui-egui/src/view_cmds.rs              |  38 ++-
 crates/ui-egui/tests/batch_export_options.rs |   8 +-
 docs/development.md                          |   2 +-
 docs/gaps.md                                 |  17 +-
 docs/scorecard.md                            |   4 +-
 docs/target-app-parity.md                    |   3 +-
 scorecard/automation.toml                    |   4 +-
 15 files changed, 972 insertions(+), 61 deletions(-)
 create mode 100644 crates/engine/src/batch.rs
 create mode 100644 crates/engine/src/batch/tests.rs

diff --git a/Cargo.lock b/Cargo.lock
index 79e7cd895e..3f1564a963 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4360,6 +4360,7 @@ name = "photocraft-engine"
 version = "0.8.2"
 dependencies = [
  "blake3",
+ "chrono",
  "craft-print",
  "exr",
  "flate2",
diff --git a/apps/photocraft-cli/src/lib.rs b/apps/photocraft-cli/src/lib.rs
index 87050381a5..f403365de3 100644
--- a/apps/photocraft-cli/src/lib.rs
+++ b/apps/photocraft-cli/src/lib.rs
@@ -27,8 +27,13 @@ USAGE:
   photocraft-cli run (<file> | --new <json>) --cmd <id> [--params <json>] [--cmd …] [--out <file>] [--format <ext>] [--quality <1-100>] [--tiff-layers] [--tga-bits <24|32>] [--dpx-bits <8|10|12|16>]
       Open a file, run engine commands in order, save the result. Each --params
       applies to the preceding --cmd. Prints each command's JSON result.
-  photocraft-cli batch --actions <actions.json|set.atn> [--action <name>] --in <dir> --out <dir> [--format <ext>] [--quality <1-100>] [--in-place] [--tiff-layers] [--tga-bits <24|32>] [--dpx-bits <8|10|12|16>]
-      Apply an action list to every image in a directory. A Photoshop Actions file (.atn) is a
+  photocraft-cli batch --actions <actions.json|set.atn> [--action <name>] --in <dir> --out <dir> [--recursive] [--naming <template>] [--start-serial <n>] [--stop-on-error] [--error-log <file>] [--format <ext>] [--quality <1-100>] [--in-place] [--tiff-layers] [--tga-bits <24|32>] [--dpx-bits <8|10|12|16>]
+      Apply an action list to every image in a directory (--recursive: its subfolders too, mirrored
+      under --out). --naming names the results, default {name}.{ext}; tokens: {name} {NAME} {Name},
+      {serial} {serial:2} {serial:3} {serial:4} (from --start-serial, default 1), {letter} {LETTER},
+      {date:mmddyy|mmdd|yyyymmdd|yymmdd|yyddmm|ddmmyy}, {ext} {EXT}; other text is literal.
+      --stop-on-error stops at the first failing file (the rest are skipped) instead of going on;
+      --error-log writes the failures to a text file. A Photoshop Actions file (.atn) is a
       set: its action --action names plays, as below. JSON steps are [id, params] pairs,
       {\"command\": id, \"params\": {…}} objects or bare ids, as a recorded action or droplet stores them
       (a list, or wrapped in {\"actions\": …}, {\"steps\": …} or a droplet). An Actions set (the Actions
@@ -79,8 +84,8 @@ const SUBCOMMANDS: &[Subcommand] = &[
     },
     Subcommand {
         name: "batch",
-        values: &["--actions", "--action", "--in", "--out", "--format", "--quality", "--tga-bits", "--dpx-bits"],
-        bare: &["--in-place", "--tiff-layers"],
+        values: &["--actions", "--action", "--in", "--out", "--naming", "--start-serial", "--error-log", "--format", "--quality", "--tga-bits", "--dpx-bits"],
+        bare: &["--in-place", "--tiff-layers", "--recursive", "--stop-on-error"],
         run: batch,
     },
     Subcommand { name: "droplet", values: &["--out"], bare: &[], run: droplet },
@@ -462,20 +467,32 @@ fn batch(a: &Args, out: &mut dyn Write, err: &mut dyn Write) -> R {
         ));
     }
     std::fs::create_dir_all(&out_dir).map_err(|e| e.to_string())?;
-    let mut inputs: Vec<PathBuf> =
-        std::fs::read_dir(&in_dir).map_err(|e| format!("{}: {e}", in_dir.display()))?.flatten().map(|e| e.path()).filter(|p| is_input(p)).collect();
-    inputs.sort();
+    let start = match a.get("--start-serial") {
+        Some(n) => n.parse::<u64>().map_err(|_| format!("--start-serial {n}: not a non-negative integer"))?,
+        None => 1,
+    };
+    let naming = photocraft_engine::batch::Naming::parse(a.get("--naming").unwrap_or(photocraft_engine::batch::Naming::DEFAULT), start)
+        .map_err(|e| format!("--naming: {e}"))?;
+    let date = photocraft_engine::batch::Date::today();
+    let stop_on_error = a.has("--stop-on-error");
+    // (file, subfolder relative to --in, mirrored under --out)
+    let inputs: Vec<(PathBuf, PathBuf)> = if a.has("--recursive") { list_inputs_recursive(&in_dir)? } else { list_inputs(&in_dir)? };
     let (mut ok, mut failed) = (0, 0);
+    let mut failures = Vec::new();
+    let mut skipped = 0;
     let mut written = photocraft_engine::file_cmds::OutputClaims::default();
     // `--format .jpg` names outputs `<stem>.jpg`, as `--format jpg` does (#490).
     let format = a.get("--format").map(|f| f.strip_prefix('.').unwrap_or(f));
-    for input in &inputs {
+    for (i, (input, sub)) in inputs.iter().enumerate() {
         let ext = format.map(str::to_owned).or_else(|| input.extension().map(|e| e.to_string_lossy().into_owned())).unwrap_or_else(|| "png".into());
         let stem = input.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_default();
-        let target = out_dir.join(format!("{stem}.{ext}"));
+        let target = out_dir.join(sub).join(naming.file_name(&stem, &ext, i as u64, date));
         let target_text = target.to_string_lossy();
         let r = (|| -> Result<Vec<String>, String> {
             written.check(&target_text)?;
+            if !sub.as_os_str().is_empty() {
+                std::fs::create_dir_all(out_dir.join(sub)).map_err(|e| format!("{}: {e}", out_dir.join(sub).display()))?;
+            }
             let mut h = Headless::trusted_local();
             // Steps that play another action find it in the set; the session's playback stack
             // stops an action that calls itself.
@@ -504,13 +521,70 @@ fn batch(a: &Args, out: &mut dyn Write, err: &mut dyn Write) -> R {
             Err(e) => {
                 failed += 1;
                 let _ = writeln!(err, "FAIL  {}: {e}", input.display());
+                failures.push(format!("{}: {e}", input.display()));
+                if stop_on_error {
+                    skipped = inputs.len() - i - 1;
+                    let _ = writeln!(err, "stopped at the first error (--stop-on-error); {skipped} file(s) skipped");
+                    break;
+                }
             }
         }
     }
-    let _ = writeln!(out, "{ok} succeeded, {failed} failed");
+    if let Some(log) = a.get("--error-log")
+        && !failures.is_empty()
+    {
+        let text = format!("PhotoCraft Batch: {} error(s)\n{}\n", failures.len(), failures.join("\n"));
+        std::fs::write(log, text).map_err(|e| format!("--error-log {log}: {e}"))?;
+    }
+    if skipped > 0 {
+        let _ = writeln!(out, "{ok} succeeded, {failed} failed, {skipped} skipped");
+    } else {
+        let _ = writeln!(out, "{ok} succeeded, {failed} failed");
+    }
     if failed > 0 { Err(format!("{failed} file(s) failed")) } else { Ok(()) }
 }
 
+/// The input images of `dir`, sorted by name, at the top (an empty subfolder).
+fn list_inputs(dir: &Path) -> Result<Vec<(PathBuf, PathBuf)>, String> {
+    let mut inputs: Vec<PathBuf> =
+        std::fs::read_dir(dir).map_err(|e| format!("{}: {e}", dir.display()))?.flatten().map(|e| e.path()).filter(|p| is_input(p)).collect();
+    inputs.sort();
+    Ok(inputs.into_iter().map(|p| (p, PathBuf::new())).collect())
+}
+
+/// The input images of `dir` and its subfolders (each folder's files sorted by name, then its
+/// subfolders), with the subfolder relative to `dir`. Links to folders are not followed; a tree
+/// deeper than the engine's limit is an error.
+fn list_inputs_recursive(dir: &Path) -> Result<Vec<(PathBuf, PathBuf)>, String> {
+    fn walk(root: &Path, sub: &Path, depth: usize, out: &mut Vec<(PathBuf, PathBuf)>) -> Result<(), String> {
+        let dir = root.join(sub);
+        let mut entries: Vec<std::fs::DirEntry> = std::fs::read_dir(&dir).map_err(|e| format!("{}: {e}", dir.display()))?.flatten().collect();
+        entries.sort_by_key(std::fs::DirEntry::file_name);
+        let mut folders = Vec::new();
+        for e in entries {
+            let Ok(ft) = e.file_type() else { continue };
+            if ft.is_dir() {
+                folders.push(e.file_name());
+            } else if is_input(&e.path()) {
+                if out.len() >= photocraft_engine::batch::MAX_FILES {
+                    return Err(format!("{}: more than {} images", root.display(), photocraft_engine::batch::MAX_FILES));
+                }
+                out.push((e.path(), sub.to_path_buf()));
+            }
+        }
+        for name in folders {
+            if depth >= photocraft_engine::batch::MAX_DEPTH {
+                return Err(format!("{}: folders nested deeper than {} levels", dir.join(&name).display(), photocraft_engine::batch::MAX_DEPTH));
+            }
+            walk(root, &sub.join(name), depth + 1, out)?;
+        }
+        Ok(())
+    }
+    let mut out = Vec::new();
+    walk(dir, Path::new(""), 0, &mut out)?;
+    Ok(out)
+}
+
 fn droplet(a: &Args, out: &mut dyn Write, err: &mut dyn Write) -> R {
     let (file, inputs) = a.positional.split_first().ok_or("droplet needs <file.pcdroplet> and inputs")?;
     if inputs.is_empty() {
@@ -753,4 +827,56 @@ mod batch_action_set_tests {
         }
         let _ = std::fs::remove_dir_all(&dir);
     }
+
+    /// `--recursive` mirrors the subfolders under `--out`, `--naming` names the results,
+    /// `--stop-on-error` skips the rest after a failure and `--error-log` records the failures.
+    #[test]
+    fn batch_recursive_naming_stop_and_log() {
+        let dir = std::env::temp_dir().join(format!("photocraft-cli-batch-opts-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let path = |name: &str| dir.join(name).to_string_lossy().to_string();
+        std::fs::create_dir_all(dir.join("in/sub")).unwrap();
+        for name in ["in/a", "in/sub/a", "in/sub/c"] {
+            let (code, _, stderr) = invoke(&["run", "--new", r#"{"width":8,"height":6}"#, "--out", &path(&format!("{name}.png"))]);
+            assert_eq!(code, 0, "{stderr}");
+        }
+        std::fs::write(dir.join("in/sub/b.png"), b"not a png").unwrap();
+        std::fs::write(dir.join("steps.json"), r#"[["image.imageRotation.90cw", {}]]"#).unwrap();
+        let (code, stdout, stderr) = invoke(&[
+            "batch",
+            "--actions",
+            &path("steps.json"),
+            "--in",
+            &path("in"),
+            "--out",
+            &path("out"),
+            "--recursive",
+            "--naming",
+            "{name}-{serial:2}.{ext}",
+            "--start-serial",
+            "5",
+            "--error-log",
+            &path("errors.txt"),
+        ]);
+        assert_ne!(code, 0, "{stdout}");
+        assert!(dir.join("out/a-05.png").is_file() && dir.join("out/sub/a-06.png").is_file() && dir.join("out/sub/c-08.png").is_file(), "{stdout}\n{stderr}");
+        assert!(stdout.contains("3 succeeded, 1 failed"), "{stdout}");
+        let log = std::fs::read_to_string(dir.join("errors.txt")).unwrap();
+        assert!(log.contains("1 error(s)") && log.contains("b.png"), "{log}");
+
+        let (code, stdout, stderr) =
+            invoke(&["batch", "--actions", &path("steps.json"), "--in", &path("in"), "--out", &path("out2"), "--recursive", "--stop-on-error"]);
+        assert_ne!(code, 0, "{stdout}");
+        assert!(stdout.contains("2 succeeded, 1 failed, 1 skipped"), "{stdout}");
+        assert!(stderr.contains("--stop-on-error"), "{stderr}");
+        assert!(!dir.join("out2/sub/c.png").exists(), "c comes after the failure and is skipped");
+
+        let (code, _, stderr) = invoke(&["batch", "--actions", &path("steps.json"), "--in", &path("in"), "--out", &path("out3"), "--naming", "{nope}"]);
+        assert_ne!(code, 0);
+        assert!(stderr.contains("--naming"), "{stderr}");
+        let (code, _, stderr) = invoke(&["batch", "--actions", &path("steps.json"), "--in", &path("in"), "--out", &path("out3"), "--start-serial", "x"]);
+        assert_ne!(code, 0);
+        assert!(stderr.contains("--start-serial"), "{stderr}");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 }
diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.toml
index 741d927a3f..6f0dfc6a47 100644
--- a/crates/engine/Cargo.toml
+++ b/crates/engine/Cargo.toml
@@ -42,6 +42,8 @@ roxmltree = "0.20"
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 tempfile = "3"
+# Batch file naming: the local date for the `{date:…}` tokens.
+chrono = { version = "0.4", default-features = false, features = ["clock"] }
 
 [dev-dependencies]
 photocraft-affinity = { workspace = true, features = ["synth"] }
diff --git a/crates/engine/src/batch.rs b/crates/engine/src/batch.rs
new file mode 100644
index 0000000000..190aae7294
--- /dev/null
+++ b/crates/engine/src/batch.rs
@@ -0,0 +1,338 @@
+//! Batch options (#219): files in subfolders, file naming, stop on error, an error log, and
+//! progress with cancel. Shared by File › Automate › Batch (which also takes the open
+//! documents as its source), Image Processor, the Lens Correction batch and the CLI's `batch`.
+//!
+//! The naming template follows Photoshop's File Naming fields as tokens in one string:
+//! `{name}` / `{NAME}` / `{Name}` (the document name as is, upper case, capitalised),
+//! `{serial}` to `{serial:4}` (a serial number, padded to that many digits, from
+//! `startSerial`), `{letter}` / `{LETTER}` (a serial letter: a, b … z, aa, ab …),
+//! `{date:mmddyy}`, `{date:mmdd}`, `{date:yyyymmdd}`, `{date:yymmdd}`, `{date:yyddmm}`,
+//! `{date:ddmmyy}` (today's date), `{ext}` / `{EXT}` (the output extension), and any other
+//! text literally. The default is `{name}.{ext}`.
+
+use serde_json::{Value, json};
+
+use crate::{EngineError, Result};
+
+/// One input of a batch: a file, and the folder it was found in relative to the input folder
+/// (`""` at the top). The output mirrors that folder, so files of the same name in different
+/// subfolders don't collide.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Input {
+    pub path: String,
+    pub subdir: String,
+}
+
+impl Input {
+    pub fn file(path: &str) -> Self {
+        Self { path: path.to_string(), subdir: String::new() }
+    }
+}
+
+fn bad(cmd: &str, msg: impl Into<String>) -> EngineError {
+    EngineError::BadParams { cmd: cmd.into(), msg: msg.into() }
+}
+
+/// The inputs of a batch command: `"input"` is a folder (with `"includeSubfolders"`, its
+/// subfolders too) or an array of files.
+pub(crate) fn inputs(p: &Value, cmd: &str) -> Result<Vec<Input>> {
+    let recurse = p.get("includeSubfolders").and_then(Value::as_bool).unwrap_or(false);
+    match p.get("input").or_else(|| p.get("files")) {
+        Some(Value::Array(a)) => Ok(a.iter().filter_map(Value::as_str).map(Input::file).collect()),
+        Some(Value::String(dir)) if recurse => list_images_recursive(dir),
+        Some(Value::String(dir)) => Ok(crate::file_cmds::list_images(dir)?.into_iter().map(|path| Input::file(&path)).collect()),
+        _ => Err(bad(cmd, "missing \"input\" (folder or array of files)")),
+    }
+}
+
+/// Deepest subfolder a recursive listing enters; deeper trees are refused rather than walked
+/// forever (a loop of symbolic links is not followed either: links to folders are skipped).
+pub const MAX_DEPTH: usize = 32;
+/// Most files a recursive listing returns.
+pub const MAX_FILES: usize = 100_000;
+
+/// The images of `dir` and its subfolders: each folder's files sorted by name, then its
+/// subfolders sorted by name.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn list_images_recursive(dir: &str) -> Result<Vec<Input>> {
+    fn walk(root: &str, sub: &str, depth: usize, out: &mut Vec<Input>) -> Result<()> {
+        let dir = if sub.is_empty() { root.to_string() } else { crate::file_cmds::join(root, sub) };
+        let rd = std::fs::read_dir(&dir).map_err(|e| EngineError::Other(format!("{dir}: {e}")))?;
+        let mut entries: Vec<std::fs::DirEntry> = rd.filter_map(|e| e.ok()).collect();
+        entries.sort_by_key(std::fs::DirEntry::file_name);
+        let mut folders = Vec::new();
+        for e in entries {
+            // `file_type` does not follow symbolic links, so a linked folder is not entered.
+            let Ok(ft) = e.file_type() else { continue };
+            let name = e.file_name().to_string_lossy().into_owned();
+            let path = e.path();
+            if ft.is_dir() {
+                folders.push(name);
+            } else if path.is_file() && crate::file_cmds::openable_name(&name) {
+                if out.len() >= MAX_FILES {
+                    return Err(EngineError::Other(format!("{root}: more than {MAX_FILES} images")));
+                }
+                out.push(Input { path: path.to_string_lossy().into_owned(), subdir: sub.to_string() });
+            }
+        }
+        for name in folders {
+            if depth >= MAX_DEPTH {
+                return Err(EngineError::Other(format!("{dir}/{name}: folders nested deeper than {MAX_DEPTH} levels")));
+            }
+            let sub = if sub.is_empty() { name } else { format!("{sub}/{name}") };
+            walk(root, &sub, depth + 1, out)?;
+        }
+        Ok(())
+    }
+    let mut out = Vec::new();
+    walk(dir, "", 0, &mut out)?;
+    Ok(out)
+}
+#[cfg(target_arch = "wasm32")]
+pub fn list_images_recursive(dir: &str) -> Result<Vec<Input>> {
+    Err(EngineError::Other(format!("cannot list {dir}: no file system on the web")))
+}
+
+/// Today's date, for the naming template's date tokens.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Date {
+    pub year: i32,
+    pub month: u32,
+    pub day: u32,
+}
+
+impl Date {
+    /// The local date. On the web (where the batch commands don't run) the epoch.
+    pub fn today() -> Self {
+        #[cfg(not(target_arch = "wasm32"))]
+        {
+            use chrono::Datelike;
+            let now = chrono::Local::now();
+            Self { year: now.year(), month: now.month(), day: now.day() }
+        }
+        #[cfg(target_arch = "wasm32")]
+        {
+            Self { year: 1970, month: 1, day: 1 }
+        }
+    }
+
+    fn format(self, fmt: DateFmt) -> String {
+        let (y, m, d) = (self.year.rem_euclid(10_000), self.month, self.day);
+        let yy = y % 100;
+        match fmt {
+            DateFmt::Mmddyy => format!("{m:02}{d:02}{yy:02}"),
+            DateFmt::Mmdd => format!("{m:02}{d:02}"),
+            DateFmt::Yyyymmdd => format!("{y:04}{m:02}{d:02}"),
+            DateFmt::Yymmdd => format!("{yy:02}{m:02}{d:02}"),
+            DateFmt::Yyddmm => format!("{yy:02}{d:02}{m:02}"),
+            DateFmt::Ddmmyy => format!("{d:02}{m:02}{yy:02}"),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum DateFmt {
+    Mmddyy,
+    Mmdd,
+    Yyyymmdd,
+    Yymmdd,
+    Yyddmm,
+    Ddmmyy,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum Case {
+    AsIs,
+    Upper,
+    Title,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+enum Seg {
+    Lit(String),
+    Name(Case),
+    /// A serial number padded to this many digits.
+    Serial(usize),
+    /// A serial letter, upper case when true.
+    Letter(bool),
+    Date(DateFmt),
+    /// The output extension, upper case when true.
+    Ext(bool),
+}
+
+/// A parsed file naming template (see the module doc).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Naming {
+    segs: Vec<Seg>,
+    start: u64,
+}
+
+impl Naming {
+    /// The template every batch uses unless told otherwise: `<document name>.<extension>`.
+    pub const DEFAULT: &'static str = "{name}.{ext}";
+
+    /// Parse `template`; serial numbers count from `start`.
+    pub fn parse(template: &str, start: u64) -> std::result::Result<Self, String> {
+        let mut segs = Vec::new();
+        let mut lit = String::new();
+        let mut rest = template;
+        while let Some(i) = rest.find('{') {
+            lit.push_str(rest.get(..i).unwrap_or_default());
+            let after = rest.get(i + 1..).unwrap_or_default();
+            let Some(j) = after.find('}') else { return Err("unclosed `{`".into()) };
+            let token = after.get(..j).unwrap_or_default();
+            let seg = match token {
+                "name" => Seg::Name(Case::AsIs),
+                "NAME" => Seg::Name(Case::Upper),
+                "Name" => Seg::Name(Case::Title),
+                "serial" => Seg::Serial(1),
+                "letter" => Seg::Letter(false),
+                "LETTER" => Seg::Letter(true),
+                "ext" => Seg::Ext(false),
+                "EXT" => Seg::Ext(true),
+                "date:mmddyy" => Seg::Date(DateFmt::Mmddyy),
+                "date:mmdd" => Seg::Date(DateFmt::Mmdd),
+                "date:yyyymmdd" => Seg::Date(DateFmt::Yyyymmdd),
+                "date:yymmdd" => Seg::Date(DateFmt::Yymmdd),
+                "date:yyddmm" => Seg::Date(DateFmt::Yyddmm),
+                "date:ddmmyy" => Seg::Date(DateFmt::Ddmmyy),
+                _ => match token.strip_prefix("serial:").and_then(|n| n.parse::<usize>().ok()) {
+                    Some(n) if (1..=4).contains(&n) => Seg::Serial(n),
+                    _ => {
+                        return Err(format!(
+                            "unknown token `{{{token}}}` (tokens: {{name}}, {{NAME}}, {{Name}}, {{serial}}, {{serial:2}}, {{serial:3}}, {{serial:4}}, {{letter}}, {{LETTER}}, {{date:mmddyy}}, {{date:mmdd}}, {{date:yyyymmdd}}, {{date:yymmdd}}, {{date:yyddmm}}, {{date:ddmmyy}}, {{ext}}, {{EXT}})"
+                        ));
+                    }
+                },
+            };
+            if !lit.is_empty() {
+                segs.push(Seg::Lit(std::mem::take(&mut lit)));
+            }
+            segs.push(seg);
+            rest = after.get(j + 1..).unwrap_or_default();
+        }
+        if rest.contains('}') {
+            return Err("stray `}`".into());
+        }
+        lit.push_str(rest);
+        if !lit.is_empty() {
+            segs.push(Seg::Lit(lit));
+        }
+        if segs.is_empty() {
+            return Err("empty".into());
+        }
+        let text: String = segs.iter().filter_map(|s| if let Seg::Lit(t) = s { Some(t.as_str()) } else { None }).collect();
+        if text.contains(['/', '\\', ':']) || text.split('.').any(|part| part == "..") {
+            return Err("file names can't contain path separators or `..`".into());
+        }
+        Ok(Self { segs, start })
+    }
+
+    /// `<name><suffix>.<ext>`, the naming of the commands without a template.
+    pub fn plain(suffix: &str) -> Self {
+        let mut segs = vec![Seg::Name(Case::AsIs)];
+        if !suffix.is_empty() {
+            segs.push(Seg::Lit(suffix.to_string()));
+        }
+        segs.extend([Seg::Lit(".".into()), Seg::Ext(false)]);
+        Self { segs, start: 1 }
+    }
+
+    /// The file name of the `index`-th (0-based) output named `stem` with extension `ext`.
+    pub fn file_name(&self, stem: &str, ext: &str, index: u64, date: Date) -> String {
+        let serial = self.start.saturating_add(index);
+        let mut out = String::new();
+        for seg in &self.segs {
+            match seg {
+                Seg::Lit(t) => out.push_str(t),
+                Seg::Name(Case::AsIs) => out.push_str(stem),
+                Seg::Name(Case::Upper) => out.push_str(&stem.to_uppercase()),
+                Seg::Name(Case::Title) => {
+                    let mut chars = stem.chars();
+                    if let Some(first) = chars.next() {
+                        out.extend(first.to_uppercase());
+                        out.push_str(&chars.as_str().to_lowercase());
+                    }
+                }
+                Seg::Serial(digits) => out.push_str(&format!("{serial:0width$}", width = *digits)),
+                Seg::Letter(upper) => out.push_str(&letters(serial, *upper)),
+                Seg::Date(fmt) => out.push_str(&date.format(*fmt)),
+                Seg::Ext(false) => out.push_str(&ext.to_lowercase()),
+                Seg::Ext(true) => out.push_str(&ext.to_uppercase()),
+            }
+        }
+        out
+    }
+}
+
+/// Serial letters: 1 → a, 26 → z, 27 → aa, 28 → ab … (0 → an empty string).
+fn letters(mut n: u64, upper: bool) -> String {
+    let mut out = Vec::new();
+    while n > 0 {
+        n -= 1;
+        let c = b'a' + (n % 26) as u8;
+        out.push(if upper { c.to_ascii_uppercase() } else { c });
+        n /= 26;
+    }
+    out.reverse();
+    String::from_utf8(out).unwrap_or_default()
+}
+
+/// How a batch run names its files and handles errors.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Options {
+    pub naming: Naming,
+    /// Stop at the first file that fails (the rest are reported as skipped) instead of going
+    /// on with the next.
+    pub stop_on_error: bool,
+    /// Write the errors of the run to this text file (Photoshop's "Log Errors to File").
+    pub error_log: Option<String>,
+}
+
+impl Options {
+    /// `naming`, `startSerial`, `stopOnError` and `errorLog` from command `cmd`'s params.
+    pub(crate) fn from_params(p: &Value, cmd: &str) -> Result<Self> {
+        let template = p.get("naming").and_then(Value::as_str).map(str::trim).filter(|t| !t.is_empty()).unwrap_or(Naming::DEFAULT);
+        let start = match p.get("startSerial") {
+            None | Some(Value::Null) => 1,
+            Some(v) => v.as_u64().ok_or_else(|| bad(cmd, "\"startSerial\" must be a non-negative integer"))?,
+        };
+        let naming = Naming::parse(template, start).map_err(|m| bad(cmd, format!("\"naming\": {m}")))?;
+        let stop_on_error = p.get("stopOnError").and_then(Value::as_bool).unwrap_or(false);
+        let error_log = p.get("errorLog").and_then(Value::as_str).map(str::trim).filter(|s| !s.is_empty()).map(str::to_string);
+        Ok(Self { naming, stop_on_error, error_log })
+    }
+
+    /// The options of the commands without them: `<name><suffix>.<ext>`, every file, no log.
+    pub fn plain(suffix: &str) -> Self {
+        Self { naming: Naming::plain(suffix), stop_on_error: false, error_log: None }
+    }
+}
+
+/// Write the errors of a run to `path`, one per line.
+pub(crate) fn write_error_log(path: &str, errors: &[Value], date: Date) -> Result<()> {
+    let mut text = format!("PhotoCraft Batch: {} error(s) on {}\n", errors.len(), date.format(DateFmt::Yyyymmdd));
+    for e in errors {
+        let what = e.get("file").or_else(|| e.get("document")).and_then(Value::as_str).unwrap_or("?");
+        let why = e.get("error").and_then(Value::as_str).unwrap_or("?");
+        text.push_str(&format!("{what}: {why}\n"));
+    }
+    crate::file_cmds::write_file(path, text.as_bytes()).map_err(|e| EngineError::Other(format!("error log: {e}")))
+}
+
+/// The outcome of a run, the shape every batch command returns.
+pub(crate) fn outcome(files: Vec<String>, errors: Vec<Value>, stopped: Option<(String, Vec<String>)>, error_log: Option<&str>) -> Value {
+    let logged = !errors.is_empty();
+    let mut r = json!({"files": files, "errors": errors});
+    if let Some((at, skipped)) = stopped {
+        r["stopped"] = json!(at);
+        r["skipped"] = json!(skipped);
+    }
+    if let (Some(log), true) = (error_log, logged) {
+        r["errorLog"] = json!(log);
+    }
+    r
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/engine/src/batch/tests.rs b/crates/engine/src/batch/tests.rs
new file mode 100644
index 0000000000..9bf47f9b2f
--- /dev/null
+++ b/crates/engine/src/batch/tests.rs
@@ -0,0 +1,248 @@
+use serde_json::{Value, json};
+
+use super::*;
+use crate::Session;
+use crate::file_cmds::{join, save_doc};
+use crate::jobs::{JobCtx, Started};
+
+fn tmp(name: &str) -> String {
+    let d = std::env::temp_dir().join(format!("photocraft-batch-{}-{name}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&d);
+    std::fs::create_dir_all(&d).unwrap();
+    d.to_string_lossy().into_owned()
+}
+
+fn png(dir: &str, name: &str, color: &str) -> String {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 8, "height": 6, "background": color})).unwrap();
+    let path = join(dir, name);
+    std::fs::create_dir_all(std::path::Path::new(&path).parent().unwrap()).unwrap();
+    save_doc(&s.active().unwrap().doc, &path, None).unwrap();
+    path
+}
+
+const DATE: Date = Date { year: 2026, month: 10, day: 12 };
+
+fn name(template: &str, start: u64, stem: &str, ext: &str, index: u64) -> String {
+    Naming::parse(template, start).unwrap().file_name(stem, ext, index, DATE)
+}
+
+#[test]
+fn naming_tokens() {
+    assert_eq!(name("{name}.{ext}", 1, "Photo", "jpg", 0), "Photo.jpg");
+    assert_eq!(name("{NAME}_{Name}.{EXT}", 1, "my Photo", "JPG", 0), "MY PHOTO_My photo.JPG");
+    assert_eq!(name("{name}-{serial}.{ext}", 1, "a", "png", 0), "a-1.png");
+    assert_eq!(name("{name}-{serial:3}.{ext}", 7, "a", "png", 2), "a-009.png");
+    assert_eq!(name("{serial:2}", 1, "a", "png", 150), "151", "a serial longer than its width keeps every digit");
+    assert_eq!(name("{letter}{LETTER}", 1, "a", "png", 0), "aA");
+    assert_eq!(name("{letter}", 1, "a", "png", 25), "z");
+    assert_eq!(name("{letter}", 1, "a", "png", 26), "aa");
+    assert_eq!(name("{LETTER}", 1, "a", "png", 27), "AB");
+    assert_eq!(
+        name("{date:mmddyy} {date:mmdd} {date:yyyymmdd} {date:yymmdd} {date:yyddmm} {date:ddmmyy}", 1, "a", "png", 0),
+        "101226 1012 20261012 261012 261210 121026"
+    );
+    assert_eq!(name("final copy.{ext}", 1, "a", "png", 0), "final copy.png", "literal text");
+    assert_eq!(Naming::plain("-x").file_name("a", "PNG", 0, DATE), "a-x.png");
+    assert_eq!(Naming::plain("").file_name("a", "jpg", 0, DATE), "a.jpg");
+    assert_eq!(Naming::parse(Naming::DEFAULT, 1).unwrap(), Naming::plain(""), "the default template is the plain naming");
+}
+
+#[test]
+fn naming_rejects_bad_templates() {
+    for (t, why) in [
+        ("{name", "unclosed"),
+        ("{name}}", "stray"),
+        ("{nope}.{ext}", "unknown token"),
+        ("{serial:5}", "unknown token"),
+        ("{serial:0}", "unknown token"),
+        ("{date:yyyy}", "unknown token"),
+        ("", "empty"),
+        ("../{name}.{ext}", "separators"),
+        ("sub/{name}", "separators"),
+        ("{name}\\x", "separators"),
+    ] {
+        let e = Naming::parse(t, 1).unwrap_err();
+        assert!(e.contains(why), "{t:?}: {e}");
+    }
+    assert_eq!(name("v1.2.{ext}", 1, "a", "png", 0), "v1.2.png", "dots inside a name are fine");
+}
+
+#[test]
+fn options_from_params() {
+    let o = Options::from_params(&json!({}), "x").unwrap();
+    assert_eq!(o, Options::plain(""));
+    let o =
+        Options::from_params(&json!({"naming": " {name}-{serial:2}.{ext} ", "startSerial": 5, "stopOnError": true, "errorLog": "/tmp/log.txt"}), "x").unwrap();
+    assert!(o.stop_on_error && o.error_log.as_deref() == Some("/tmp/log.txt"));
+    assert_eq!(o.naming.file_name("a", "png", 0, DATE), "a-05.png");
+    let e = Options::from_params(&json!({"naming": "{bad}"}), "x").unwrap_err();
+    assert!(e.to_string().contains("naming"), "{e}");
+    assert!(Options::from_params(&json!({"startSerial": -1}), "x").is_err());
+    assert!(Options::from_params(&json!({"startSerial": 1.5}), "x").is_err());
+    assert_eq!(Options::from_params(&json!({"naming": "", "errorLog": "  "}), "x").unwrap(), Options::plain(""), "empty strings mean the defaults");
+}
+
+#[test]
+fn recursive_listing_mirrors_folders() {
+    let dir = tmp("list");
+    png(&dir, "b.png", "#ffffff");
+    png(&dir, "a.png", "#ffffff");
+    png(&dir, "sub/z.png", "#ffffff");
+    png(&dir, "sub/inner/y.png", "#ffffff");
+    png(&dir, "zsub/x.png", "#ffffff");
+    std::fs::write(join(&dir, "sub/notes.txt"), "no").unwrap();
+    let flat = inputs(&json!({"input": dir}), "x").unwrap();
+    assert_eq!(flat.iter().map(|i| crate::file_cmds::file_name(&i.path)).collect::<Vec<_>>(), ["a.png", "b.png"], "without the flag, only the top folder");
+    let all = inputs(&json!({"input": dir, "includeSubfolders": true}), "x").unwrap();
+    let got: Vec<(String, &str)> = all.iter().map(|i| (crate::file_cmds::file_name(&i.path), i.subdir.as_str())).collect();
+    assert_eq!(
+        got,
+        [("a.png".to_string(), ""), ("b.png".into(), ""), ("z.png".into(), "sub"), ("y.png".into(), "sub/inner"), ("x.png".into(), "zsub")],
+        "each folder's files, then its subfolders, sorted by name"
+    );
+    assert!(list_images_recursive(&join(&dir, "missing")).is_err());
+}
+
+#[test]
+fn batch_into_subfolders_with_a_naming_template() {
+    let dir = tmp("batch");
+    let input = join(&dir, "in");
+    png(&input, "a.png", "#ff0000");
+    png(&input, "sub/a.png", "#00ff00");
+    let out = join(&dir, "out");
+    let mut s = Session::new();
+    let r = s
+        .execute(
+            "file.automate.batch",
+            json!({"steps": [["image.adjustments.invert", {}]], "input": input, "includeSubfolders": true, "output": out, "format": "png", "naming": "{name}_{serial:2}.{ext}", "startSerial": 10}),
+        )
+        .unwrap();
+    let files: Vec<&str> = r["files"].as_array().unwrap().iter().filter_map(Value::as_str).collect();
+    assert_eq!(files, [join(&out, "a_10.png"), join(&out, "sub/a_11.png")], "{r}");
+    assert!(r["errors"].as_array().unwrap().is_empty() && r.get("stopped").is_none(), "{r}");
+    for f in files {
+        assert!(std::path::Path::new(f).is_file(), "{f} written");
+    }
+    // Without the mirrored folders the two a.png would collide: the second is reported.
+    let r = s
+        .execute(
+            "file.automate.batch",
+            json!({"steps": [], "input": [join(&input, "a.png"), join(&input, "sub/a.png")], "output": join(&dir, "flat"), "format": "png"}),
+        )
+        .unwrap();
+    assert_eq!(r["files"].as_array().unwrap().len(), 1);
+    assert_eq!(r["errors"].as_array().unwrap().len(), 1, "{r}");
+}
+
+#[test]
+fn stop_on_error_skips_the_rest_and_logs() {
+    let dir = tmp("stop");
+    let input = join(&dir, "in");
+    png(&input, "a.png", "#ff0000");
+    std::fs::write(join(&input, "b.png"), b"not a png").unwrap();
+    png(&input, "c.png", "#0000ff");
+    let out = join(&dir, "out");
+    let log = join(&dir, "errors.txt");
+    let mut s = Session::new();
+    let p = json!({"steps": [], "input": input, "output": out, "format": "png", "errorLog": log});
+    let r = s.execute("file.automate.batch", p.clone()).unwrap();
+    assert_eq!((r["files"].as_array().unwrap().len(), r["errors"].as_array().unwrap().len()), (2, 1), "every file is tried: {r}");
+    assert!(r.get("stopped").is_none());
+    assert_eq!(r["errorLog"], json!(log));
+    let text = std::fs::read_to_string(&log).unwrap();
+    assert!(text.starts_with("PhotoCraft Batch: 1 error(s)") && text.contains("b.png: "), "{text}");
+
+    let mut p = p;
+    p["stopOnError"] = json!(true);
+    p["output"] = json!(join(&dir, "out2"));
+    let r = s.execute("file.automate.batch", p).unwrap();
+    assert_eq!((r["files"].as_array().unwrap().len(), r["errors"].as_array().unwrap().len()), (1, 1), "{r}");
+    // Folder listings carry the platform's separators (`\` on Windows): compare the file names.
+    let name = |v: &Value| crate::file_cmds::file_name(v.as_str().unwrap());
+    assert_eq!(name(&r["stopped"]), "b.png", "{r}");
+    assert_eq!(r["skipped"].as_array().unwrap().iter().map(name).collect::<Vec<_>>(), ["c.png"], "{r}");
+    assert!(!std::path::Path::new(&join(&dir, "out2/c.png")).exists(), "c was not processed");
+
+    // No errors: no log is written (an old one is not touched either).
+    std::fs::remove_file(&log).unwrap();
+    let r = s
+        .execute("file.automate.batch", json!({"steps": [], "input": [join(&input, "a.png")], "output": join(&dir, "out3"), "format": "png", "errorLog": log}))
+        .unwrap();
+    assert!(r.get("errorLog").is_none() && !std::path::Path::new(&log).exists(), "{r}");
+}
+
+#[test]
+fn a_cancelled_run_stops_and_still_logs() {
+    let dir = tmp("cancel");
+    let input = join(&dir, "in");
+    let a = png(&input, "a.png", "#ff0000");
+    let log = join(&dir, "errors.txt");
+    let ctx = JobCtx::new();
+    ctx.cancel();
+    let options = Options { naming: Naming::plain(""), stop_on_error: false, error_log: Some(log.clone()) };
+    let r = crate::file_cmds::process_files(&[Input::file(&a)], &join(&dir, "out"), "png", Default::default(), &options, Some(&ctx), &|_| Ok(()));
+    assert!(matches!(r, Err(crate::EngineError::Cancelled)), "{r:?}");
+    assert!(!std::path::Path::new(&join(&dir, "out/a.png")).exists(), "nothing was written after the cancel");
+}
+
+#[test]
+fn batch_runs_as_a_background_job_with_progress() {
+    let dir = tmp("job");
+    let input = join(&dir, "in");
+    png(&input, "a.png", "#ff0000");
+    png(&input, "b.png", "#00ff00");
+    let out = join(&dir, "out");
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 4, "height": 4})).unwrap();
+    let r = s.start("file.automate.batch", json!({"steps": [["image.adjustments.invert", {}]], "input": input, "output": out, "format": "png"})).unwrap();
+    let Started::Job(id) = r else { panic!("expected a job: {r:?}") };
+    let v = s.wait_job(id).unwrap();
+    assert_eq!(v["files"].as_array().unwrap().len(), 2, "{v}");
+    assert!(s.active().is_some_and(|d| d.doc.size.width == 4), "the open document is untouched");
+}
+
+#[test]
+fn source_open_runs_the_steps_on_every_open_document() {
+    let dir = tmp("open");
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 8, "height": 6, "background": "white", "name": "First"})).unwrap();
+    s.execute("file.new", json!({"width": 8, "height": 6, "background": "white", "name": "Second"})).unwrap();
+    s.set_active(0);
+    let out = join(&dir, "out");
+    let r = s
+        .execute(
+            "file.automate.batch",
+            json!({"steps": [["image.adjustments.invert", {}]], "source": "open", "output": out, "format": "png", "naming": "{serial:2}-{name}.{ext}"}),
+        )
+        .unwrap();
+    assert_eq!(r["documents"], 2);
+    let files: Vec<&str> = r["files"].as_array().unwrap().iter().filter_map(Value::as_str).collect();
+    assert_eq!(files, [join(&out, "01-First.png"), join(&out, "02-Second.png")], "{r}");
+    assert_eq!(s.active_index(), Some(0), "the active document is restored");
+    for d in s.documents() {
+        let px = photocraft_compose::render(&d.doc, photocraft_geom::Rect::new(1, 1, 2, 2)).px[0];
+        assert!(px[0] < 0.01, "both documents were inverted: {px:?}");
+        assert!(d.history.can_undo(), "as undoable steps");
+    }
+    // Destination None: no output, the documents just change.
+    let r = s.execute("file.automate.batch", json!({"steps": [["image.adjustments.invert", {}]], "source": "open"})).unwrap();
+    assert!(r["files"].as_array().unwrap().is_empty() && r["errors"].as_array().unwrap().is_empty(), "{r}");
+    // "same" on an untitled document saves a PSD.
+    let r = s.execute("file.automate.batch", json!({"steps": [], "source": "open", "output": join(&dir, "same")})).unwrap();
+    assert!(r["files"][0].as_str().unwrap().ends_with("First.psd"), "{r}");
+    // A failing step with stop on error.
+    let r = s
+        .execute(
+            "file.automate.batch",
+            json!({"steps": [["layer.delete", {"layer": 999_999}]], "source": "open", "stopOnError": true, "errorLog": join(&dir, "log.txt")}),
+        )
+        .unwrap();
+    assert_eq!(r["errors"].as_array().unwrap().len(), 1, "{r}");
+    assert_eq!(r["stopped"], "First");
+    assert_eq!(r["skipped"], json!(["Second"]));
+    assert!(std::fs::read_to_string(join(&dir, "log.txt")).unwrap().contains("First: "));
+    assert!(s.execute("file.automate.batch", json!({"steps": [], "source": "nope"})).is_err());
+    let mut empty = Session::new();
+    assert!(empty.execute("file.automate.batch", json!({"steps": [], "source": "open"})).is_err());
+}
diff --git a/crates/engine/src/file_cmds.rs b/crates/engine/src/file_cmds.rs
index 7470e78231..666ae16d1a 100644
--- a/crates/engine/src/file_cmds.rs
+++ b/crates/engine/src/file_cmds.rs
@@ -96,6 +96,12 @@ pub(crate) fn write_file(path: &str, _bytes: &[u8]) -> Result<()> {
     Err(EngineError::Other(format!("cannot write {path}: no file system on the web")))
 }
 
+/// Whether a file name's extension is one the batch commands open.
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) fn openable_name(name: &str) -> bool {
+    name.rsplit_once('.').is_some_and(|(_, ext)| OPENABLE.contains(&ext.to_ascii_lowercase().as_str()))
+}
+
 /// Files of a folder that look like images we can open, sorted by name.
 #[cfg(not(target_arch = "wasm32"))]
 pub fn list_images(dir: &str) -> Result<Vec<String>> {
@@ -919,25 +925,57 @@ fn parse_steps(v: &Value) -> Result<Vec<(String, Value)>> {
         .collect()
 }
 
-/// Inputs of a batch command: `"input"` is a folder or an array of files.
-pub(crate) fn batch_inputs(p: &Value, cmd: &str) -> Result<Vec<String>> {
-    match p.get("input").or_else(|| p.get("files")) {
-        Some(Value::Array(a)) => Ok(a.iter().filter_map(Value::as_str).map(str::to_string).collect()),
-        Some(Value::String(dir)) => list_images(dir),
-        _ => Err(EngineError::BadParams { cmd: cmd.into(), msg: "missing \"input\" (folder or array of files)".into() }),
-    }
+/// Inputs of a batch command: `"input"` is a folder (with `"includeSubfolders"`, its subfolders
+/// too) or an array of files. See [`crate::batch::inputs`].
+pub(crate) fn batch_inputs(p: &Value, cmd: &str) -> Result<Vec<crate::batch::Input>> {
+    crate::batch::inputs(p, cmd)
 }
 
-/// Opens each input in a scratch session, runs `f` on it and saves it to `output` as `format`
-/// (`"same"` keeps the input's extension). Errors per file are collected, not fatal.
-pub(crate) fn process_files(inputs: &[String], output: &str, format: &str, save: SaveOpts, suffix: &str, f: &dyn Fn(&mut Session) -> Result<()>) -> Value {
+#[cfg(not(target_arch = "wasm32"))]
+fn ensure_dir(dir: &str) -> Result<()> {
+    std::fs::create_dir_all(dir).map_err(|e| EngineError::Other(format!("{dir}: {e}")))
+}
+#[cfg(target_arch = "wasm32")]
+fn ensure_dir(dir: &str) -> Result<()> {
+    Err(EngineError::Other(format!("cannot create {dir}: no file system on the web")))
+}
+
+/// Opens each input in a scratch session, runs `f` on it and saves it to `output` (in the
+/// input's subfolder, mirrored) as `format` (`"same"` keeps the input's extension), named by
+/// `options.naming`. Errors per file are collected, not fatal, unless `options.stop_on_error`;
+/// they also go to `options.error_log` when set. With a job context, progress is reported per
+/// file and a cancel stops after the current file (`Err(Cancelled)`; the files written so far
+/// stay, the log is still written).
+pub(crate) fn process_files(
+    inputs: &[crate::batch::Input],
+    output: &str,
+    format: &str,
+    save: SaveOpts,
+    options: &crate::batch::Options,
+    ctx: Option<&crate::jobs::JobCtx>,
+    f: &dyn Fn(&mut Session) -> Result<()>,
+) -> Result<Value> {
     let mut files = Vec::new();
     let mut errors = Vec::new();
     let mut written = OutputClaims::default();
-    for path in inputs {
+    let date = crate::batch::Date::today();
+    let total = inputs.len();
+    let mut stopped = None;
+    let mut cancelled = false;
+    let mut done = 0;
+    for (i, input) in inputs.iter().enumerate() {
+        if let Some(ctx) = ctx {
+            if ctx.cancelled() {
+                cancelled = true;
+                break;
+            }
+            ctx.progress(i as f32 / total.max(1) as f32, &format!("{} of {total}: {}", i + 1, file_name(&input.path)));
+        }
+        let path = &input.path;
         let ext =
             if format == "same" { path.rsplit('.').next().unwrap_or("png").to_ascii_lowercase() } else { format.trim_start_matches('.').to_ascii_lowercase() };
-        let out = join(output, &format!("{}{suffix}.{ext}", stem(path)));
+        let dir = if input.subdir.is_empty() { output.to_string() } else { join(output, &input.subdir) };
+        let out = join(&dir, &options.naming.file_name(&stem(path), &ext, i as u64, date));
         let r = (|| -> Result<()> {
             written.check(&out).map_err(EngineError::Other)?;
             let bytes = read_file(path)?;
@@ -946,18 +984,38 @@ pub(crate) fn process_files(inputs: &[String], output: &str, format: &str, save:
             scratch.add_document(doc, Some(path.clone()));
             f(&mut scratch)?;
             let d = scratch.active().ok_or(EngineError::NoDocument)?;
+            ensure_dir(&dir)?;
             save_doc(&d.doc, &out, save)?;
             Ok(())
         })();
+        done = i + 1;
         match r {
             Ok(()) => {
                 written.record(&out, path);
                 files.push(out);
             }
-            Err(e) => errors.push(json!({"file": path, "error": e.to_string()})),
+            Err(e) => {
+                errors.push(json!({"file": path, "error": e.to_string()}));
+                if options.stop_on_error {
+                    stopped = Some(path.clone());
+                    break;
+                }
+            }
         }
     }
-    json!({"files": files, "errors": errors})
+    if let Some(log) = &options.error_log
+        && !errors.is_empty()
+    {
+        crate::batch::write_error_log(log, &errors, date)?;
+    }
+    if cancelled {
+        return Err(EngineError::Cancelled);
+    }
+    if let Some(ctx) = ctx {
+        ctx.progress(1.0, "");
+    }
+    let skipped = || inputs.iter().skip(done).map(|i| i.path.clone()).collect();
+    Ok(crate::batch::outcome(files, errors, stopped.map(|at| (at, skipped())), options.error_log.as_deref()))
 }
 
 /// The output paths a batch run has written, so a later input whose output name matches an
@@ -992,9 +1050,12 @@ fn batch(s: &mut Session, p: &Value) -> Result<Value> {
     if let Some((id, _)) = steps.iter().find(|(id, _)| crate::commands::find(id).is_none()) {
         return Err(EngineError::BadParams { cmd: cmd.into(), msg: format!("unknown command `{id}` in the action") });
     }
-    let inputs = batch_inputs(p, cmd)?;
-    let output = str_param(p, "output", cmd)?.to_string();
+    let options = crate::batch::Options::from_params(p, cmd)?;
     let format = p.get("format").and_then(Value::as_str).unwrap_or("same").to_string();
+    let source = p.get("source").and_then(Value::as_str).unwrap_or("folder");
+    if !matches!(source, "folder" | "open") {
+        return Err(EngineError::BadParams { cmd: cmd.into(), msg: format!("unknown source `{source}` (folder or open)") });
+    }
     // Steps that call another action play it from the caller's actions; the playback stack comes
     // along so an action that batches itself is caught as a recursive call.
     let list = match p.get("calledActions") {
@@ -1010,17 +1071,109 @@ fn batch(s: &mut Session, p: &Value) -> Result<Value> {
         }
     };
     let actions = crate::actions_cmds::ActionState { list, playing: s.actions.playing, playback_stack: s.actions.playback_stack.clone(), ..Default::default() };
-    let r = process_files(&inputs, &output, &format, SaveOpts::from_params(s, p, cmd)?, "", &|scratch| {
-        scratch.actions = actions.clone();
-        for (id, params) in &steps {
-            let r = scratch.execute(id, params.clone())?;
-            // A failed step inside a called action makes this file an error, not a saved result.
-            if let Some(error) = crate::actions_cmds::nested_failure(id, &r) {
-                return Err(EngineError::Other(error));
+    let save = SaveOpts::from_params(s, p, cmd)?;
+    if source == "open" {
+        return batch_open_documents(s, &steps, p, &options, &format, save, cmd);
+    }
+    let inputs = batch_inputs(p, cmd)?;
+    let output = str_param(p, "output", cmd)?.to_string();
+    // The files are processed on a worker when started as a job (the UI does): the status bar
+    // shows "n of total: file" and Cancel stops after the current file.
+    crate::jobs::run(
+        s,
+        "Batch",
+        false,
+        move |ctx| {
+            process_files(&inputs, &output, &format, save, &options, Some(ctx), &|scratch| {
+                scratch.actions = actions.clone();
+                for (id, params) in &steps {
+                    let r = scratch.execute(id, params.clone())?;
+                    // A failed step inside a called action makes this file an error, not a saved result.
+                    if let Some(error) = crate::actions_cmds::nested_failure(id, &r) {
+                        return Err(EngineError::Other(error));
+                    }
+                }
+                Ok(())
+            })
+        },
+        |_, v| Ok(v),
+    )
+}
+
+/// Batch with Source: Opened Files. The steps run on every open document in turn (as history
+/// steps of each); with `"output"` a copy of each is saved there, named by the template from
+/// the document's name (an untitled document saved as `"same"` becomes a PSD, as it would in
+/// Photoshop); without, the documents just stay changed (Destination: None).
+fn batch_open_documents(
+    s: &mut Session,
+    steps: &[(String, Value)],
+    p: &Value,
+    options: &crate::batch::Options,
+    format: &str,
+    save: SaveOpts,
+    cmd: &str,
+) -> Result<Value> {
+    let n = s.documents().len();
+    if n == 0 {
+        return Err(EngineError::NoDocument);
+    }
+    let output = p.get("output").and_then(Value::as_str).map(str::trim).filter(|o| !o.is_empty()).map(str::to_string);
+    let date = crate::batch::Date::today();
+    let prev = s.active_index();
+    let mut files = Vec::new();
+    let mut errors = Vec::new();
+    let mut written = OutputClaims::default();
+    let mut stopped = None;
+    let mut done = 0;
+    let names: Vec<String> = s.documents().iter().map(|d| d.path.clone().unwrap_or_else(|| d.doc.name.clone())).collect();
+    for (i, name) in names.iter().enumerate() {
+        if !s.set_active(i) {
+            break;
+        }
+        let r = (|| -> Result<()> {
+            for (id, params) in steps {
+                let r = s.execute(id, params.clone())?;
+                if let Some(error) = crate::actions_cmds::nested_failure(id, &r) {
+                    return Err(EngineError::Other(error));
+                }
+            }
+            let Some(output) = &output else { return Ok(()) };
+            let ext = if format == "same" {
+                let d = s.documents().get(i).ok_or(EngineError::NoDocument)?;
+                d.path.as_deref().and_then(|p| p.rsplit_once('.')).map(|(_, e)| e.to_ascii_lowercase()).unwrap_or_else(|| "psd".into())
+            } else {
+                format.trim_start_matches('.').to_ascii_lowercase()
+            };
+            let out = join(output, &options.naming.file_name(&stem(name), &ext, i as u64, date));
+            written.check(&out).map_err(EngineError::Other)?;
+            ensure_dir(output)?;
+            let d = s.documents().get(i).ok_or(EngineError::NoDocument)?;
+            save_doc(&d.doc, &out, save)?;
+            written.record(&out, name);
+            files.push(out);
+            Ok(())
+        })();
+        done = i + 1;
+        if let Err(e) = r {
+            errors.push(json!({"document": name, "error": e.to_string()}));
+            if options.stop_on_error {
+                stopped = Some(name.clone());
+                break;
             }
         }
-        Ok(())
-    });
+    }
+    if let Some(i) = prev {
+        s.set_active(i);
+    }
+    if let Some(log) = &options.error_log
+        && !errors.is_empty()
+    {
+        crate::batch::write_error_log(log, &errors, date)?;
+    }
+    let _ = cmd;
+    let skipped = || names.iter().skip(done).cloned().collect();
+    let mut r = crate::batch::outcome(files, errors, stopped.map(|at| (at, skipped())), options.error_log.as_deref());
+    r["documents"] = json!(n);
     Ok(r)
 }
 
@@ -1034,7 +1187,8 @@ fn image_processor(s: &mut Session, p: &Value) -> Result<Value> {
         (w, h) => Some(json!({"width": w.unwrap_or(1e9), "height": h.unwrap_or(1e9), "dontEnlarge": true})),
     };
     let to_srgb = p.get("convertToSrgb").and_then(Value::as_bool).unwrap_or(false);
-    let r = process_files(&inputs, &output, &format, SaveOpts::from_params(s, p, cmd)?.or_quality(8.0), "", &|scratch| {
+    let options = crate::batch::Options::from_params(p, cmd)?;
+    process_files(&inputs, &output, &format, SaveOpts::from_params(s, p, cmd)?.or_quality(8.0), &options, None, &|scratch| {
         if to_srgb && scratch.active().is_some_and(|d| d.doc.mode != ColorMode::Rgb) {
             scratch.execute("image.mode.rgb", json!({}))?;
         }
@@ -1042,8 +1196,7 @@ fn image_processor(s: &mut Session, p: &Value) -> Result<Value> {
             fit_image(scratch, fp)?;
         }
         Ok(())
-    });
-    Ok(r)
+    })
 }
 
 fn load_files_into_stack(s: &mut Session, p: &Value) -> Result<Value> {
@@ -1535,7 +1688,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Batch…",
             &["File", "Automate"],
             None,
-            r##"{"steps":[[commandId,params]|{"command":id,"params":{}}…] (a recorded action),"input":folder|[paths],"output":folder,"format":"same|png|jpg|psd|tiff|…"="same","quality":0..12?,"tiffLayers":bool=false,"tgaBits":24|32?,"dpxBits":8|10|12|16? (DPX: bits per sample; unset, 8 for an 8-bit document, else 16),"calledActions":[{"name","steps"}…]? (the actions Play Action steps call; default: the session's)} → {files, errors} (an input whose output name was already written in the run goes to errors)"##,
+            r##"{"steps":[[commandId,params]|{"command":id,"params":{}}…] (a recorded action),"source":"folder|open"="folder" (open: the steps run on every open document; "input" is ignored, "output" optional: a copy of each is saved there, else they just stay changed),"input":folder|[paths],"includeSubfolders":bool=false (the output mirrors the subfolders),"output":folder,"format":"same|png|jpg|psd|tiff|…"="same","naming":"{name}.{ext}"? (template: {name} {NAME} {Name} {serial} {serial:2..4} {letter} {LETTER} {date:mmddyy|mmdd|yyyymmdd|yymmdd|yyddmm|ddmmyy} {ext} {EXT}, other text literal),"startSerial":int=1,"stopOnError":bool=false (else every file is tried),"errorLog":path? (the errors, one per line),"quality":0..12?,"tiffLayers":bool=false,"tgaBits":24|32?,"dpxBits":8|10|12|16? (DPX: bits per sample; unset, 8 for an 8-bit document, else 16),"calledActions":[{"name","steps"}…]? (the actions Play Action steps call; default: the session's)} → {files, errors, stopped?, skipped?, errorLog?} (an input whose output name was already written in the run goes to errors). Runs as a job: progress per file, Cancel stops after the current one"##,
             native,
             batch
         ),
@@ -1544,7 +1697,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Image Processor…",
             &["File", "Scripts"],
             None,
-            r##"{"input":folder|[paths],"output":folder,"format":"jpg|png|psd|tiff|…"="jpg","quality":0..12=8,"tiffLayers":bool=false,"tgaBits":24|32?,"dpxBits":8|10|12|16? (DPX: bits per sample; unset, 8 for an 8-bit document, else 16),"width":px?,"height":px? (fit, never enlarge),"convertToSrgb":bool=false} → {files, errors} (an input whose output name was already written in the run goes to errors)"##,
+            r##"{"input":folder|[paths],"includeSubfolders":bool=false,"output":folder,"format":"jpg|png|psd|tiff|…"="jpg","naming":"{name}.{ext}"? (as file.automate.batch),"startSerial":int=1,"stopOnError":bool=false,"errorLog":path?,"quality":0..12=8,"tiffLayers":bool=false,"tgaBits":24|32?,"dpxBits":8|10|12|16? (DPX: bits per sample; unset, 8 for an 8-bit document, else 16),"width":px?,"height":px? (fit, never enlarge),"convertToSrgb":bool=false} → {files, errors, stopped?, skipped?, errorLog?} (an input whose output name was already written in the run goes to errors)"##,
             native,
             image_processor
         ),
diff --git a/crates/engine/src/lens_cmds.rs b/crates/engine/src/lens_cmds.rs
index 379ca2402a..ba8078fc99 100644
--- a/crates/engine/src/lens_cmds.rs
+++ b/crates/engine/src/lens_cmds.rs
@@ -418,20 +418,20 @@ fn lens_batch(s: &mut Session, p: &Value) -> Result<Value> {
     let format = p.get("format").and_then(Value::as_str).unwrap_or("same").to_string();
     let mut params = p.clone();
     if let Value::Object(m) = &mut params {
-        for k in ["input", "files", "output", "format", "quality"] {
+        for k in ["input", "files", "includeSubfolders", "output", "format", "naming", "startSerial", "stopOnError", "errorLog", "quality"] {
             m.remove(k);
         }
         // Batch default: the EXIF-driven profile, as Photoshop's dialog suggests.
         m.entry("profile").or_insert(json!("auto"));
     }
-    let r = crate::file_cmds::process_files(&inputs, &output, &format, crate::file_cmds::SaveOpts::from_params(s, p, LENS_BATCH)?, "", &|scratch| {
+    let options = crate::batch::Options::from_params(p, LENS_BATCH)?;
+    crate::file_cmds::process_files(&inputs, &output, &format, crate::file_cmds::SaveOpts::from_params(s, p, LENS_BATCH)?, &options, None, &|scratch| {
         if scratch.active().is_some_and(|d| d.doc.layers.len() > 1) {
             scratch.execute("layer.flattenImage", json!({}))?;
         }
         scratch.execute(LENS, params.clone())?;
         Ok(())
-    });
-    Ok(r)
+    })
 }
 
 const LENS_DOC: &str = r##"{"profile":"none|auto|generic","focalLength":mm=0,"correctDistortion":bool=true,"correctVignette":bool=true,"correctCA":bool=true,"autoScale":bool=false,"distortion":-100..100=0,"redCyan":-100..100=0,"blueYellow":-100..100=0,"vignetteAmount":-100..100=0,"vignetteMidpoint":0..100=50,"vertical":-100..100=0,"horizontal":-100..100=0,"angle":-180..180=0,"scale":50..150=100,"edge":"transparency|edgeExtension|black|white","straighten":[[x,y],[x,y]]?}"##;
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 58a8974298..01afc3aa04 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -18,6 +18,7 @@ pub mod artboard_cmds;
 pub mod atn_cmds;
 pub mod automate_cmds;
 pub mod background_cmds;
+pub mod batch;
 pub mod brush_cmds;
 pub mod brush_key_cmds;
 pub mod brush_preset_cmds;
diff --git a/crates/ui-egui/src/view_cmds.rs b/crates/ui-egui/src/view_cmds.rs
index f18c4730e2..8b83a2f01b 100644
--- a/crates/ui-egui/src/view_cmds.rs
+++ b/crates/ui-egui/src/view_cmds.rs
@@ -1049,6 +1049,31 @@ mod form_reset_tests {
     }
 }
 
+/// The fields a `__form` dialog shows, in order: as `__order` lists them (a dialog's grouping,
+/// such as Batch's Play / Source / Destination / Errors), the rest alphabetically after them.
+fn form_keys(f: &Map<String, Value>) -> Vec<String> {
+    let mut keys: Vec<String> = f.keys().filter(|k| !k.starts_with("__")).cloned().collect();
+    if let Some(order) = f.get("__order").and_then(Value::as_array) {
+        let order: Vec<&str> = order.iter().filter_map(Value::as_str).collect();
+        keys.sort_by_key(|k| order.iter().position(|o| o == k).unwrap_or(usize::MAX));
+    }
+    keys
+}
+
+#[cfg(test)]
+mod form_order_tests {
+    use super::form_keys;
+    use serde_json::json;
+
+    #[test]
+    fn order_hint_puts_listed_fields_first_and_the_rest_alphabetically() {
+        let f = json!({"zeta": 1, "alpha": 2, "mid": 3, "__order": ["mid", "zeta"], "__form": true});
+        assert_eq!(form_keys(f.as_object().unwrap()), ["mid", "zeta", "alpha"]);
+        let f = json!({"b": 1, "a": 2});
+        assert_eq!(form_keys(f.as_object().unwrap()), ["a", "b"], "without a hint, alphabetical as before");
+    }
+}
+
 /// Body of a `__form` dialog: text fields, number fields, checkboxes and `__choices` dropdowns.
 pub fn form_body(ui: &mut egui::Ui, f: &mut Map<String, Value>) {
     let choices = f.get("__choices").cloned().unwrap_or(Value::Null);
@@ -1056,7 +1081,7 @@ pub fn form_body(ui: &mut egui::Ui, f: &mut Map<String, Value>) {
     // come from `__labels` verbatim; everything else goes through the catalogue.
     let labels = f.get("__labels").cloned().unwrap_or(Value::Null);
     let label = |k: &str| labels.get(k).and_then(Value::as_str).map_or_else(|| label_of(k), str::to_string);
-    let keys: Vec<String> = f.keys().filter(|k| !k.starts_with("__")).cloned().collect();
+    let keys = form_keys(f);
     egui::Grid::new("form-dialog").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| {
         for k in keys {
             let v = f.get(&k).cloned().unwrap_or(Value::Null);
@@ -1307,10 +1332,17 @@ fn front(app: &mut PhotocraftApp, id: &str, params: &Value) -> Option<Result<Val
             };
             let steps = crate::actions::action_steps(action);
             let name = action.name.clone();
+            // Photoshop's Batch dialog: Source (folder with Include All Subfolders, or the open
+            // documents), Destination, File Naming, Errors (stop, or log to a file).
             dialog(
                 app,
-                json!({"action": name, "steps": steps, "input": dir, "output": format!("{dir}/batch"), "format": "same", "quality": null, "__batchQuality": 8}),
-                json!({"format": ["same", "png", "jpg", "psd", "tiff", "webp"]}),
+                json!({
+                    "action": name, "steps": steps, "source": "folder", "input": dir, "includeSubfolders": false,
+                    "output": format!("{dir}/batch"), "format": "same", "naming": photocraft_engine::batch::Naming::DEFAULT, "startSerial": 1,
+                    "stopOnError": false, "errorLog": "", "quality": null, "__batchQuality": 8,
+                    "__order": ["action", "source", "input", "includeSubfolders", "output", "format", "naming", "startSerial", "quality", "stopOnError", "errorLog"],
+                }),
+                json!({"format": ["same", "png", "jpg", "psd", "tiff", "webp"], "source": ["folder", "open"]}),
             )
         }
         // Channel workflow dialogs (see channels_panel.rs for the channel references).
diff --git a/crates/ui-egui/tests/batch_export_options.rs b/crates/ui-egui/tests/batch_export_options.rs
index 7de3b2869d..9490de507e 100644
--- a/crates/ui-egui/tests/batch_export_options.rs
+++ b/crates/ui-egui/tests/batch_export_options.rs
@@ -71,10 +71,11 @@ fn replace_text(h: &mut Harness, value: &str) {
 fn edit_path(h: &mut Harness, name: &str, value: &Path) {
     let label = h.get_by_label(name).rect();
     h.query_all_by_role(egui::accesskit::Role::TextInput)
-        .find(|n| {
+        .filter(|n| {
             let r = n.rect();
             r.left() >= label.right() && (r.center().y - label.center().y).abs() < 3.0
         })
+        .min_by_key(|n| n.rect().left() as i32)
         .expect("path text field beside its label")
         .click();
     h.run_steps(2);
@@ -85,11 +86,14 @@ fn edit_path(h: &mut Harness, name: &str, value: &Path) {
 
 fn edit_quality(h: &mut Harness, value: &str) {
     let label = h.get_by_label("Quality").rect();
+    // The nearest numeric field to the right on the label's row: a panel's field (the Layers
+    // panel's opacity) can share the row's height now that the dialog is taller.
     h.query_all_by_role(egui::accesskit::Role::SpinButton)
-        .find(|n| {
+        .filter(|n| {
             let r = n.rect();
             r.left() >= label.right() && (r.center().y - label.center().y).abs() < 3.0
         })
+        .min_by_key(|n| n.rect().left() as i32)
         .expect("quality numeric field beside its label")
         .click();
     h.run_steps(2);
diff --git a/docs/development.md b/docs/development.md
index bb0de12690..7b7042b247 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -161,7 +161,7 @@ cargo run -p photocraft-cli -- batch --actions actions.json --in photos/ --out d
 cargo run -p photocraft-cli -- commands --filter blur                    # the command registry
 ```
 
-`actions.json` holds the steps of a recorded action: `[["<id>", {…}], …]`, `[{"command": "<id>", "params": {…}}, …]` or bare ids, as a list or wrapped in `{"actions": …}` or `{"steps": …}`; a droplet file works too. It can also be an Actions set (the Actions panel's `actions.json`, `{"actions": [{"name": …, "steps": […]}, …]}`): `--action <name>` picks the action to play (optional when the set holds one), and the whole set is loaded for each file, so a step that plays another action of the set works. `batch` refuses an `--out` folder that is the `--in` folder, since the results would replace the originals, unless `--in-place` is given. `run` prints one JSON line per command result.
+`actions.json` holds the steps of a recorded action: `[["<id>", {…}], …]`, `[{"command": "<id>", "params": {…}}, …]` or bare ids, as a list or wrapped in `{"actions": …}` or `{"steps": …}`; a droplet file works too. It can also be an Actions set (the Actions panel's `actions.json`, `{"actions": [{"name": …, "steps": […]}, …]}`): `--action <name>` picks the action to play (optional when the set holds one), and the whole set is loaded for each file, so a step that plays another action of the set works. `batch` refuses an `--out` folder that is the `--in` folder, since the results would replace the originals, unless `--in-place` is given. `--recursive` takes the subfolders too and mirrors them under `--out`; `--naming <template>` names the results (default `{name}.{ext}`; tokens `{name}` `{NAME}` `{Name}`, `{serial}` to `{serial:4}` counting from `--start-serial`, `{letter}` `{LETTER}`, `{date:mmddyy|mmdd|yyyymmdd|yymmdd|yyddmm|ddmmyy}`, `{ext}` `{EXT}`, other text literal); `--stop-on-error` stops at the first failing file and `--error-log <file>` writes the failures to a text file. The same options are `includeSubfolders`, `naming`, `startSerial`, `stopOnError` and `errorLog` on `file.automate.batch` (which also takes `"source": "open"` for the open documents, and reports progress and takes Cancel as a job), Image Processor and the lens batch. `run` prints one JSON line per command result.
 
 ## Native format (.pcraft)
 
diff --git a/docs/gaps.md b/docs/gaps.md
index 23b3751235..7eb2b852a8 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -1,6 +1,6 @@
 # Where PhotoCraft falls short of Photoshop
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-13 · **Change:** minor (G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-13 · **Change:** minor (G11: Batch subfolders, naming, stop/log, cancel landed, AUTO-219-5 done; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed) · **Target:** Adobe Photoshop 2026
 
 Every known shortfall against Photoshop 2026 (27.11.0), one entry each, ranked by user impact
 on the way to beta. This is the work list agents pick from: take the highest-ranked entry that
@@ -88,11 +88,15 @@ what an agent can't finish alone.
 - **Estimate:** 120–200 h.
 
 ### G11. Actions and scripting
-- **Missing:** document-independent action recording (AUTO-219-1), Batch recursion and naming
-  (AUTO-219-5), ExtendScript/UXP compatibility. `.atn` steps outside the
-  mapped events (paths, scripts, Generative Fill, Filter Gallery effects other than Spatter,
-  Duplicate Layers into a new document, Bitmap halftone screens…) load as kept Photoshop steps
-  that fail at playback by name.
+- **Missing:** document-independent action recording (AUTO-219-1), ExtendScript/UXP compatibility.
+  `.atn` steps outside the mapped events (paths, scripts, Generative Fill, Filter Gallery effects
+  other than Spatter, Duplicate Layers into a new document, Bitmap halftone screens…) load as kept
+  Photoshop steps that fail at playback by name.
+- **Done 2026-10-12:** Batch (AUTO-219-5): Include All Subfolders (the output mirrors the
+  tree), the open documents as the source, a File Naming template (`{name}`, serial numbers and
+  letters, dates, `{ext}`), Stop For Errors with the skipped files reported, Log Errors To File;
+  it runs as a job with per-file progress and Cancel. The Batch dialog, Image Processor, the
+  lens batch and the CLI's `batch` share the options.
 - **Done 2026-10-12:** Load/Save Actions `.atn` in the panel menu, `batch --actions set.atn`
   and `actions.load`/`actions.save`; 112 Photoshop events map to commands both ways (Transform,
   Apply Image, Save for Web, smart-object edits, Gradient Map, Quick Mask, polygon selections,
@@ -266,6 +270,7 @@ what an agent can't finish alone.
 | 2026-10-12 | minor | G4: checkbox-only Brush Settings rows preserve the open controls and Smoothing settings (#4283); no readiness percentage or estimate changed |
 | 2026-10-12 | minor | G11: Load/Save Actions `.atn` landed (AUTO-219-2 partial); remaining panel work listed |
 | 2026-10-12 | minor | Refreshed against main: G5 items fixed by #2480, #2327, #2609, #2684, #2675, #2556, #2396, #2527, #2625 and TOOL-214-5/#2442; G7 TOOL-214-7 and Transform On Drop done; G2 #2377 fixed (#2417); G9 UI scale (UI-217-9) and Stamp Visible (UI-217-22) done, prefs 27 of 156; G10 #2225 done (#2482); G13 Khmer, Lao, Myanmar fallback (#3259); G14 CR3 line; G17 Windows ARM64 done (DIST-220-2) |
+| 2026-10-12 | minor | G11: Batch subfolders, open documents, naming template, stop/log, progress and cancel landed (AUTO-219-5 done) |
 | 2026-10-11 | minor | D5100 image area and Camera Raw tuning validation; G14 remains open |
 | 2026-10-11 | minor | G13: Czech dynamic UI text localized; engine messages and native review remain open |
 | 2026-10-11 | minor | G8: triple/quadruple/five-click type selection done (TYPE-218-8, #3493); Type evidence recounted |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index 1ad3f3aa3d..073b493460 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -11,7 +11,7 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
 | [Tools](#tools) | 28 | 14 | 1 |  |
 | [Workspace and UI](#workspace-and-ui) | 13 | 6 | 4 | settings that do nothing: 26 of 156 (target 0) |
 | [Type](#type) | 4 | 3 | 2 |  |
-| [Automation](#automation) | 5 | 2 | 4 | 631 of 631 menu items live (100.0%) |
+| [Automation](#automation) | 6 | 1 | 4 | 631 of 631 menu items live (100.0%) |
 | [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 28 of 28 crates; panic_hunt present |
 | [Distribution](#distribution) | 5 | 4 | 2 |  |
 | [Open bugs](#open-bugs) | 29 | 2 | 1 |  |
@@ -231,7 +231,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
-| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | partial | [#219](https://github.com/storytold/photocraft/issues/219) | file_cmds.rs:590-631 folder/array input, per-file errors; no recursion, template or cancel |
+| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | done | [#219](https://github.com/storytold/photocraft/issues/219) | batch.rs + file_cmds.rs: includeSubfolders (output mirrors the tree), source open (the open documents), naming template ({name} {serial:n} {letter} {date:…} {ext}, startSerial), stopOnError with the skipped files, errorLog file; runs as a job with per-file progress and Cancel; the Batch dialog, Image Processor, the lens batch and the CLI (--recursive --naming --start-serial --stop-on-error --error-log) share it |
 | AUTO-219-6 | Plug-in ABI v2: panel kind, progress/cancel calls, read other layers, Last Filter repeats | missing | [#219](https://github.com/storytold/photocraft/issues/219) | runtime.rs:15 ABI_VERSION = 1; manifest.rs:18 Kind::Filter only |
 | AUTO-219-7 | Local ONNX models behind a flag, managed in Preferences; subject select, background removal | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No ONNX runtime dependency |
 | AUTO-219-8 | xtask check that every panel button routes through a command id | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No such xtask check |
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index f6209c58db..2ace4ab3aa 100644
--- a/docs/target-app-parity.md
+++ b/docs/target-app-parity.md
@@ -177,7 +177,7 @@ parity for the area and are already contained in the dimension rows above.
 | Vector shapes and paths | 55% | 80–140 | Pen, Direct/Path Selection, shapes, shape strokes. Freeform and Curvature Pen (#1054). Add/Delete Anchor Point and Convert Point tools exist (`Tool` enum); missing on-canvas corner radius (TOOL-214-12), path-point nudge; shape parity tracking issue #2496 |
 | Colour management and modes | 70% | 60–100 | Own ICC engine, soft proof, CMYK/Lab/Indexed/Duotone/Multichannel; no Adobe CMYK profiles, no spot plates (FILE-215-17), monitor profile only at launch |
 | Camera Raw and computational photo (Photomerge, HDR, lens) | 45% | 120–200 | Raw for DNG/CR2/NEF/ARW/RW2/ORF/RAF(uncompressed)/PEF; no CR3; ACR dialog partial (no masking, calibration); generic lens profiles only |
-| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; Actions panel and recording not document-independent (AUTO-219-1/2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); no ExtendScript/UXP |
+| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; Actions panel and recording not document-independent (AUTO-219-1/2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); Batch complete since 2026-10-12 (subfolders, open documents, naming, stop/log, cancel); no ExtendScript/UXP |
 | File I/O | 60% | 300–500 | See [file-format-parity.md](file-format-parity.md) |
 | Print, export, Save for Web | 50% | 60–100 | JPEG Options dialog missing (FILE-215-19), no Photoshop PDF, no separations, Save for Web settings not remembered |
 | Video / timeline, data-driven graphics | 30% | 100–200 | Menu items live; frame model persists in `.pcraft`; no PSD video-layer mapping |
@@ -567,6 +567,7 @@ See [method, raw measurements and reproduction](five-algorithm-performance.md).
 | 2026-10-12 | minor | `.atn` import: 112 events mapped (TrueGrit Texture Supply sets play end to end); percentages unchanged |
 | 2026-10-12 | minor | Photoshop Actions `.atn` load and save (90 events mapped both ways); percentages unchanged |
 | 2026-10-12 | minor | Rows checked against `main` and the regenerated scorecard: menu count 631, Workspace checklist and preference count, transform context menu, Puppet Warp mesh, Select and Mask, anchor-point tools, Smart Object conversion, Stamp Visible, mask targeting, Free Transform commit/cancel, Vietnamese catalog, Windows ARM64; percentages, weights and hours not re-measured |
+| 2026-10-12 | minor | Batch: subfolders, open documents, naming template, stop/log, progress and cancel (AUTO-219-5); percentages unchanged |
 | 2026-10-10 | minor | Added measured Tilt-Shift computation/filtered-proxy gains and inconclusive cases; parity percentages and budgets unchanged |
 | 2026-10-10 | minor | Readiness-by-audience table: percent and hours for full, mainstream and essentials; full number confirmed as the additive weighted sum over dimensions (46%, reported ~45%) |
 | 2026-10-10 | minor | Added mainstream-practitioner (~43%) and essentials-user (~61%) numbers with written weights and discounts; full ready-for-real-work rechecked against its written weights (46%, reported ~45%), unchanged |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index 0de2ab3bd2..a5906ebc42 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -42,9 +42,9 @@ note = "actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document record
 [[item]]
 id = "AUTO-219-5"
 target = "Batch: subfolders, open documents, naming template, progress/cancel, error log, stop"
-status = "partial"
+status = "done"
 issue = 219
-note = "file_cmds.rs:590-631 folder/array input, per-file errors; no recursion, template or cancel"
+note = "batch.rs + file_cmds.rs: includeSubfolders (output mirrors the tree), source open (the open documents), naming template ({name} {serial:n} {letter} {date:…} {ext}, startSerial), stopOnError with the skipped files, errorLog file; runs as a job with per-file progress and Cancel; the Batch dialog, Image Processor, the lens batch and the CLI (--recursive --naming --start-serial --stop-on-error --error-log) share it"
 
 [[item]]
 id = "AUTO-219-6"

From 6c12e0bc20ed03776a21ed97f36f0c98cbbdef07 Mon Sep 17 00:00:00 2001
From: vistaero <vistaero@outlook.com>
Date: Sat, 10 Oct 2026 07:49:47 +0200
Subject: [PATCH 003/109] Integrate streamed PSB output with the shared save
 service

---
 apps/photocraft/src/services.rs           | 139 +++++++++++++++++++++-
 crates/automation/src/files.rs            |   2 +-
 crates/automation/src/headless.rs         |   9 +-
 crates/automation/src/workspace.rs        |  28 ++++-
 crates/engine/src/file_cmds.rs            |  22 ++--
 crates/format/src/atomic/tests.rs         |  33 +++++
 crates/io/src/lib.rs                      |  88 ++++++++++----
 crates/io/src/psd_export.rs               |   6 +-
 crates/io/src/psd_stream.rs               |  52 ++++++--
 crates/io/tests/streamed_save.rs          | 102 ++++++++++++++++
 crates/io/tests/streaming_psd.rs          |   3 +-
 crates/ui-egui/src/lib.rs                 |  33 +++--
 crates/ui-egui/src/save_identity_tests.rs |  37 ++++++
 docs/roadmap.md                           |   2 +
 docs/streaming-io.md                      |   3 +-
 docs/streaming-save.md                    |  27 +++++
 16 files changed, 523 insertions(+), 63 deletions(-)
 create mode 100644 crates/io/tests/streamed_save.rs
 create mode 100644 docs/streaming-save.md

diff --git a/apps/photocraft/src/services.rs b/apps/photocraft/src/services.rs
index 3cae110ea3..e28dc6df80 100644
--- a/apps/photocraft/src/services.rs
+++ b/apps/photocraft/src/services.rs
@@ -273,13 +273,60 @@ fn save_through(
     Ok(r.warnings)
 }
 
+/// A save on a worker thread (`Services::save_file`, #2017): encode, then write atomically.
+/// Encoding writes an owned temporary, leaving the destination untouched. After the final
+/// flush, `commit` makes atomic publication uncancellable.
 fn save_file(
     doc: &Document,
     path: &str,
     settings: &photocraft_ui_egui::ExportSettings,
     ctl: &photocraft_ui_egui::jobs_ui::SaveCtl,
 ) -> Result<Vec<String>, String> {
-    save_through(doc, path, settings, ctl, |p, b, progress| write_atomic_progress(Path::new(p), b, progress))
+    if !photocraft_io::needs_psb_stream(doc, path, &export_options(settings)) {
+        return save_through(doc, path, settings, ctl, |p, b, progress| write_atomic_progress(Path::new(p), b, progress));
+    }
+    ctl.progress(0.0, "Encoding");
+    let opts = export_options(settings);
+    let cancelled = || ctl.check().is_err();
+    let progress = |fraction| ctl.progress(fraction * 0.95, "Encoding");
+    let interrupt = photocraft_raster::Interrupt::new(&cancelled, &progress);
+    crate::crash_guard::guard("Save", || {
+        photocraft_io::export_path_with_commit(doc, Path::new(path), &opts, &interrupt, || {
+            ctl.commit().map_err(photocraft_io::IoError::Unsupported)?;
+            ctl.progress(0.97, "Writing");
+            Ok(())
+        })
+        .map_err(|e| e.to_string())
+    })
+    .inspect(|_| {
+        ctl.progress(1.0, "");
+    })
+}
+
+fn export_authorized(
+    workspace: &photocraft_automation::AuthorizedWorkspace,
+    doc: &Document,
+    path: &str,
+    settings: &photocraft_ui_egui::ExportSettings,
+) -> Result<Vec<String>, String> {
+    let opts = export_options(settings);
+    crate::crash_guard::guard("Save", || {
+        if photocraft_io::needs_psb_stream(doc, path, &opts) {
+            let mut warnings = Vec::new();
+            workspace
+                .write_stream(path, |out| {
+                    warnings = photocraft_io::export_psb_into_with_options(doc, out, &opts, &photocraft_raster::Interrupt::NONE)
+                        .map_err(|e| std::io::Error::other(e.to_string()))?;
+                    Ok(())
+                })
+                .map_err(|e| e.to_string())?;
+            Ok(warnings)
+        } else {
+            let result = photocraft_io::export(doc, path, &opts).map_err(|e| e.to_string())?;
+            workspace.write(path, &result.bytes).map_err(|e| e.to_string())?;
+            Ok(result.warnings)
+        }
+    })
 }
 
 type SharedRecovery = Rc<RefCell<Option<RecoveryStore>>>;
@@ -411,6 +458,10 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
             crate::crash_guard::guard("Open", || workspace.read_document(path, ctl).map_err(|e| e.to_string()))
         }) as photocraft_ui_egui::AutomationImportPathFn
     });
+    let automation_export_path = automation.clone().map(|workspace| {
+        Box::new(move |doc: &Document, path: &str, settings: &photocraft_ui_egui::ExportSettings| export_authorized(&workspace, doc, path, settings))
+            as photocraft_ui_egui::ExportPathFn
+    });
     let automation_read = automation.clone().map(|workspace| {
         Box::new(move |path: &str| {
             let bytes = workspace.read(path).map_err(|error| error.to_string())?;
@@ -430,7 +481,32 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
     });
     let automation_save = automation.clone().map(|workspace| {
         std::sync::Arc::new(move |doc: &Document, path: &str, settings: &photocraft_ui_egui::ExportSettings, ctl: &photocraft_ui_egui::jobs_ui::SaveCtl| {
-            save_through(doc, path, settings, ctl, |p, b, _| workspace.write(p, b).map_err(|e| e.to_string()))
+            if !photocraft_io::needs_psb_stream(doc, path, &export_options(settings)) {
+                return save_through(doc, path, settings, ctl, |p, b, _| workspace.write(p, b).map_err(|e| e.to_string()));
+            }
+            let cancelled = || ctl.check().is_err();
+            let progress = |p| ctl.progress(p * 0.95, "Encoding");
+            let interrupt = photocraft_raster::Interrupt::new(&cancelled, &progress);
+            crate::crash_guard::guard("Save", || {
+                let mut warnings = Vec::new();
+                workspace
+                    .write_stream_with_commit(
+                        path,
+                        |out| {
+                            warnings = photocraft_io::export_psb_into_with_options(doc, out, &export_options(settings), &interrupt)
+                                .map_err(|e| std::io::Error::other(e.to_string()))?;
+                            Ok(())
+                        },
+                        || {
+                            ctl.commit().map_err(std::io::Error::other)?;
+                            ctl.progress(0.97, "Writing");
+                            Ok(())
+                        },
+                    )
+                    .map_err(|e| e.to_string())?;
+                ctl.progress(1.0, "");
+                Ok(warnings)
+            })
         }) as photocraft_ui_egui::SaveFileFn
     });
     let step: fn(&str, &serde_json::Value) -> photocraft_engine::Result<()> = photocraft_automation::workspace::authorize_desktop_engine_step;
@@ -450,6 +526,11 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
             let opts = export_options(settings);
             crate::crash_guard::guard("Export", || photocraft_io::export(doc, path, &opts).map(|r| (r.bytes, r.warnings)).map_err(|e| e.to_string()))
         })),
+        export_path: Some(Box::new(|doc, path, settings| {
+            crate::crash_guard::guard("Save", || {
+                photocraft_io::export_path_with(doc, Path::new(path), &export_options(settings), &photocraft_raster::Interrupt::NONE).map_err(|e| e.to_string())
+            })
+        })),
         save_file: Some(Arc::new(save_file)),
         file_dialog: Some(Box::new(show_file_dialog)),
         write: Some(Box::new(|path: &str, bytes: &[u8]| write_atomic(Path::new(path), bytes))),
@@ -458,6 +539,7 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
         automation_write,
         automation_open_pcraft,
         automation_save,
+        automation_export_path,
         automation_command,
         automation_authorize,
         encode_png: Some(Box::new(|w, h, rgba| {
@@ -603,6 +685,59 @@ mod tests {
     use photocraft_ui_egui::{PhotocraftApp, prefs_ui};
     use serde_json::{Value, json};
 
+    #[test]
+    fn native_streamed_save_finishes_the_original_document_after_a_tab_switch() {
+        let dir = temp("streamed-save-job");
+        let path = dir.join("original.psb").to_string_lossy().into_owned();
+        let mut session = Session::new();
+        session.execute("file.new", json!({"width":32,"height":16,"depth":16})).unwrap();
+        session.execute("layer.new.layer", json!({})).unwrap();
+        session.execute("edit.fill", json!({"color":"#336699"})).unwrap();
+        let original = session.active().unwrap().doc.id;
+        let revision = session.active().unwrap().revision;
+        let services = Services { save_file: Some(Arc::new(save_file)), ..Default::default() };
+        let mut app = PhotocraftApp::new(session, services);
+        app.background_jobs = true;
+        let reply = app.save_as(Some(path.clone())).unwrap();
+        assert_eq!(reply["pending"], true);
+        assert!(app.session.execute("edit.fill", json!({"color":"#ffffff"})).is_err(), "upstream save lock is retained");
+        app.session.execute("file.new", json!({"width":4,"height":4})).unwrap();
+        let current = app.session.active().unwrap().doc.id;
+        let context = egui::Context::default();
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(15);
+        while app.session.has_jobs() && std::time::Instant::now() < deadline {
+            photocraft_ui_egui::jobs_ui::tick(&mut app, &context);
+            std::thread::sleep(std::time::Duration::from_millis(2));
+        }
+        assert!(!app.session.has_jobs());
+        assert_eq!(app.session.active().unwrap().doc.id, current);
+        let saved = app.session.documents().iter().find(|s| s.doc.id == original).unwrap();
+        assert_eq!(saved.path.as_deref(), Some(path.as_str()));
+        assert_eq!(saved.saved_revision, revision);
+        let reopened = photocraft_io::import_path_with("saved", Path::new(&path), &photocraft_raster::Interrupt::NONE).unwrap();
+        assert_eq!(reopened.document.size, saved.doc.size);
+        assert_eq!(reopened.document.depth, saved.doc.depth);
+        assert_eq!(photocraft_compose::flatten(&reopened.document).px, photocraft_compose::flatten(&saved.doc).px);
+    }
+
+    #[test]
+    fn native_authorized_stream_save_rejects_ambient_and_parent_paths() {
+        let dir = temp("streamed-save-authority");
+        let workspace = photocraft_automation::AuthorizedWorkspace::new(Some(&dir), Some(&dir)).unwrap();
+        let mut session = Session::new();
+        session.execute("file.new", json!({"width":4,"height":4})).unwrap();
+        let doc = &session.active().unwrap().doc;
+        let settings = photocraft_ui_egui::ExportSettings::default();
+        assert!(export_authorized(&workspace, doc, "../outside.psb", &settings).is_err());
+        let absolute = dir.join("absolute.psb");
+        export_authorized(&workspace, doc, &absolute.to_string_lossy(), &settings).unwrap();
+        assert!(export_authorized(&workspace, doc, &dir.parent().unwrap().join("outside.psb").to_string_lossy(), &settings).is_err());
+        export_authorized(&workspace, doc, "allowed.psb", &settings).unwrap();
+        assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 2);
+        let reopened = workspace.read_document("allowed.psb", &photocraft_raster::Interrupt::NONE).unwrap();
+        assert_eq!(reopened.document.size, doc.size);
+    }
+
     #[cfg(all(unix, not(target_os = "macos")))]
     #[test]
     fn open_filters_cover_uppercase_and_mixed_case_extensions() {
diff --git a/crates/automation/src/files.rs b/crates/automation/src/files.rs
index 61c6ba246a..d119d8da7b 100644
--- a/crates/automation/src/files.rs
+++ b/crates/automation/src/files.rs
@@ -82,7 +82,7 @@ pub fn save(
         return Ok(Vec::new());
     }
     #[cfg(not(target_arch = "wasm32"))]
-    if ext == "psb" || ext == "psd" && (opts.force_psb || doc.size.width > 30_000 || doc.size.height > 30_000) {
+    if photocraft_io::needs_psb_stream(doc, &format!("output.{ext}"), opts) {
         let mut warnings = Vec::new();
         photocraft_format::atomic::atomic_write_stream(path, |file| {
             warnings = photocraft_io::export_psb_into(doc, file, &photocraft_raster::Interrupt::NONE).map_err(|e| std::io::Error::other(e.to_string()))?;
diff --git a/crates/automation/src/headless.rs b/crates/automation/src/headless.rs
index 3a61ffa4dc..f036e4b5f5 100644
--- a/crates/automation/src/headless.rs
+++ b/crates/automation/src/headless.rs
@@ -260,10 +260,11 @@ impl Headless {
             }
             Filesystem::Workspace(workspace) => {
                 #[cfg(not(target_arch = "wasm32"))]
-                if format
-                    .map(|f| f.trim_start_matches('.').eq_ignore_ascii_case("psb"))
-                    .unwrap_or_else(|| target.extension().is_some_and(|ext| ext.eq_ignore_ascii_case("psb")))
-                {
+                if photocraft_io::needs_psb_stream(
+                    &doc,
+                    &format.map(|f| format!("output.{}", f.trim_start_matches('.'))).unwrap_or_else(|| target_text.to_string()),
+                    opts,
+                ) {
                     let mut warnings = Vec::new();
                     workspace.write_stream(target_text, |file| {
                         warnings = photocraft_io::export_psb_into(&doc, file, &photocraft_raster::Interrupt::NONE)
diff --git a/crates/automation/src/workspace.rs b/crates/automation/src/workspace.rs
index 6321bc241f..a379b15c80 100644
--- a/crates/automation/src/workspace.rs
+++ b/crates/automation/src/workspace.rs
@@ -102,6 +102,16 @@ impl AuthorizedWorkspace {
     /// Atomically publish a seekable encoder through the held write capability. No ambient
     /// paths are exposed to the encoder, including for temporary-file creation and rename.
     pub fn write_stream(&self, path: &str, encode: impl FnOnce(&mut cap_std::fs::File) -> std::io::Result<()>) -> Result<(), AutomationError> {
+        self.write_stream_with_commit(path, encode, || Ok(()))
+    }
+
+    /// Approve publication after encoding and flushing; rejection preserves the old destination.
+    pub fn write_stream_with_commit(
+        &self,
+        path: &str,
+        encode: impl FnOnce(&mut cap_std::fs::File) -> std::io::Result<()>,
+        commit: impl FnOnce() -> std::io::Result<()>,
+    ) -> Result<(), AutomationError> {
         struct Cleanup(Arc<Dir>, PathBuf);
         impl Drop for Cleanup {
             fn drop(&mut self) {
@@ -120,7 +130,9 @@ impl AuthorizedWorkspace {
         // This binding drops before the cleanup guard if an encoder unwinds.
         let mut file = file;
         let written = encode(&mut file).and_then(|()| photocraft_format::atomic::sync_file(&file.into_std()));
-        let renamed = written.and_then(|()| photocraft_format::atomic::retry_rename(RenameRetry::platform(), || root.dir.rename(&tmp, &root.dir, &relative)));
+        let renamed = written
+            .and_then(|()| commit())
+            .and_then(|()| photocraft_format::atomic::retry_rename(RenameRetry::platform(), || root.dir.rename(&tmp, &root.dir, &relative)));
         if let Err(e) = renamed {
             let _ = root.dir.remove_file(&tmp);
             return Err(file_error("write", path, e));
@@ -524,6 +536,20 @@ mod tests {
         assert_eq!(std::fs::read(inside.join("kept.psb")).unwrap(), b"0007payload");
     }
 
+    #[test]
+    fn seekable_capability_rejected_commit_preserves_destination_and_cleans_temporary() {
+        let (inside, _, workspace) = roots("stream-commit-rejected");
+        std::fs::write(inside.join("kept.psb"), b"original").unwrap();
+        let result = workspace.write_stream_with_commit(
+            "kept.psb",
+            |file| file.write_all(b"replacement"),
+            || Err(std::io::Error::new(std::io::ErrorKind::Interrupted, "cancelled before publication")),
+        );
+        assert!(result.is_err());
+        assert_eq!(std::fs::read(inside.join("kept.psb")).unwrap(), b"original");
+        assert!(temp_files(&inside).is_empty());
+    }
+
     #[test]
     fn seekable_capability_unwind_removes_temporary_after_closing_handle() {
         let (inside, _, workspace) = roots("stream-unwind");
diff --git a/crates/engine/src/file_cmds.rs b/crates/engine/src/file_cmds.rs
index 58c4e6ca7f..d616a24350 100644
--- a/crates/engine/src/file_cmds.rs
+++ b/crates/engine/src/file_cmds.rs
@@ -331,10 +331,7 @@ pub fn dpx_bits_param(p: &Value, cmd: &str) -> Result<Option<photocraft_io::DpxB
     }
 }
 
-/// Encodes `doc` for `path`'s extension.
-pub(crate) fn encode(doc: &Document, path: &str, save: impl Into<SaveOpts>) -> Result<(Vec<u8>, Vec<String>)> {
-    crate::allocation::checkpoint("saving document")?;
-    let save = save.into();
+fn save_options(doc: &Document, save: SaveOpts) -> photocraft_io::ExportOptions {
     let mut opts = photocraft_io::ExportOptions {
         tiff_layers: save.tiff_layers,
         tga_bits: save.tga_bits,
@@ -353,20 +350,21 @@ pub(crate) fn encode(doc: &Document, path: &str, save: impl Into<SaveOpts>) -> R
         opts.encode.webp_quality = q;
         opts.encode.webp_lossless = false;
     }
+    opts
+}
+
+/// Encodes `doc` for `path`'s extension.
+pub(crate) fn encode(doc: &Document, path: &str, save: impl Into<SaveOpts>) -> Result<(Vec<u8>, Vec<String>)> {
+    crate::allocation::checkpoint("saving document")?;
+    let opts = save_options(doc, save.into());
     photocraft_io::export(doc, path, &opts).map(|r| (r.bytes, r.warnings)).map_err(|e| EngineError::Other(format!("{path}: {e}")))
 }
 
 pub(crate) fn save_doc(doc: &Document, path: &str, save: impl Into<SaveOpts>) -> Result<Vec<String>> {
     #[cfg(not(target_arch = "wasm32"))]
     {
-        let save = save.into();
-        let mut opts = photocraft_io::ExportOptions { tiff_layers: save.tiff_layers, ..Default::default() };
-        if let Some(q) = save.quality {
-            let q = (q.clamp(0.0, 12.0) / 12.0 * 99.0 + 1.0).round() as u8;
-            opts.encode.jpeg_quality = q;
-            opts.encode.webp_quality = q;
-            opts.encode.webp_lossless = false;
-        }
+        crate::allocation::checkpoint("saving document")?;
+        let opts = save_options(doc, save.into());
         photocraft_io::export_path_with(doc, std::path::Path::new(path), &opts, &photocraft_raster::Interrupt::NONE)
             .map_err(|e| EngineError::Other(format!("{path}: {e}")))
     }
diff --git a/crates/format/src/atomic/tests.rs b/crates/format/src/atomic/tests.rs
index eef149d476..9b7b176246 100644
--- a/crates/format/src/atomic/tests.rs
+++ b/crates/format/src/atomic/tests.rs
@@ -349,3 +349,36 @@ fn streaming_encoder_unwind_closes_and_removes_temporary_file() {
     assert_eq!(std::fs::read(&p).unwrap(), ORIGINAL);
     assert_no_temp(&d.0);
 }
+
+#[cfg(windows)]
+#[test]
+fn streaming_read_only_temporary_is_removed_on_rejected_or_unwinding_commit() {
+    for unwind in [false, true] {
+        let dir = TempDir::new("stream-read-only");
+        let path = dir.0.join("document.psb");
+        std::fs::write(&path, ORIGINAL).unwrap();
+        let mut permissions = std::fs::metadata(&path).unwrap().permissions();
+        permissions.set_readonly(true);
+        std::fs::set_permissions(&path, permissions).unwrap();
+        let result = std::panic::catch_unwind(|| {
+            atomic_write_stream_with_commit(
+                &path,
+                |file| file.write_all(b"complete"),
+                || {
+                    if unwind {
+                        panic!("injected read-only commit panic");
+                    }
+                    Err(io::Error::new(io::ErrorKind::Interrupted, "cancelled before commit"))
+                },
+            )
+        });
+        if unwind {
+            assert!(result.is_err());
+        } else {
+            assert_eq!(result.unwrap().unwrap_err().kind(), io::ErrorKind::Interrupted);
+        }
+        assert_eq!(std::fs::read(&path).unwrap(), ORIGINAL);
+        assert!(std::fs::metadata(&path).unwrap().permissions().readonly());
+        assert_no_temp(&dir.0);
+    }
+}
diff --git a/crates/io/src/lib.rs b/crates/io/src/lib.rs
index 0cb2b481f9..15f72cf26f 100644
--- a/crates/io/src/lib.rs
+++ b/crates/io/src/lib.rs
@@ -502,36 +502,84 @@ pub fn export_with(doc: &Document, name_or_ext: &str, opts: &ExportOptions, ctl:
 /// formats with only a bytes encoder use the checked working-set admission in [`export`].
 #[cfg(not(target_arch = "wasm32"))]
 pub fn export_path_with(doc: &Document, path: &std::path::Path, opts: &ExportOptions, ctl: &photocraft_raster::Interrupt<'_>) -> Result<Vec<String>, IoError> {
+    export_path_with_commit(doc, path, opts, ctl, || Ok(()))
+}
+
+/// Whether native output needs the bounded PSB writer, including automatic PSD size promotion.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn needs_psb_stream(doc: &Document, name: &str, opts: &ExportOptions) -> bool {
+    let ext = extension(name);
+    ext == "psb" || ext == "psd" && (opts.force_psb || doc.size.width > 30_000 || doc.size.height > 30_000 || psd_export::psd_size_exceeds_limit(doc))
+}
+
+/// Encode and flush an owned temporary, then call `commit` immediately before publication.
+/// After commit succeeds, no cancellation check may turn a successful publication into failure.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn export_path_with_commit(
+    doc: &Document,
+    path: &std::path::Path,
+    opts: &ExportOptions,
+    ctl: &photocraft_raster::Interrupt<'_>,
+    commit: impl FnOnce() -> Result<(), IoError>,
+) -> Result<Vec<String>, IoError> {
+    use std::io::Write;
     ctl.check().map_err(|_| IoError::Cancelled)?;
-    let ext = path.extension().and_then(|s| s.to_str()).unwrap_or("").to_ascii_lowercase();
-    if ext == "psb" || ext == "psd" && (opts.force_psb || doc.size.width > 30_000 || doc.size.height > 30_000) {
+    let mut warnings = Vec::new();
+    let mut commit_error = None;
+    let streaming = needs_psb_stream(doc, &path.to_string_lossy(), opts);
+    let encoded = if streaming {
         photocraft_raster::spill::check_integrity().map_err(IoError::Unsupported)?;
-        let mut warnings = Vec::new();
-        let result = photocraft_format::atomic::atomic_write_stream_with_commit(
-            path,
-            |out| {
-                warnings = psd_stream::export_into(doc, out, *ctl).map_err(|e| std::io::Error::other(e.to_string()))?;
+        None
+    } else {
+        let result = export_with(doc, &path.to_string_lossy(), opts, ctl)?;
+        warnings = result.warnings;
+        Some(result.bytes)
+    };
+    let result = photocraft_format::atomic::atomic_write_stream_with_commit(
+        path,
+        |out| {
+            if let Some(bytes) = encoded {
+                out.write_all(&bytes)
+            } else {
+                warnings = psd_stream::export_into(doc, out, opts, *ctl).map_err(|e| std::io::Error::other(e.to_string()))?;
                 Ok(())
-            },
-            || ctl.check().map_err(|e| std::io::Error::new(std::io::ErrorKind::Interrupted, e)),
-        );
-        if result.is_err() && ctl.cancelled() {
-            return Err(IoError::Cancelled);
-        }
-        result.map_err(|e| IoError::Unsupported(e.to_string()))?;
-        return Ok(warnings);
+            }
+        },
+        || {
+            ctl.check().map_err(|e| std::io::Error::new(std::io::ErrorKind::Interrupted, e))?;
+            commit().map_err(|e| {
+                let message = e.to_string();
+                commit_error = Some(e);
+                std::io::Error::other(message)
+            })
+        },
+    );
+    if let Some(error) = commit_error {
+        return Err(error);
     }
-    let result = export(doc, &path.to_string_lossy(), opts)?;
-    ctl.check().map_err(|_| IoError::Cancelled)?;
-    photocraft_format::atomic_write(path, &result.bytes).map_err(|e| IoError::Unsupported(e.to_string()))?;
-    Ok(result.warnings)
+    if result.is_err() && ctl.cancelled() {
+        return Err(IoError::Cancelled);
+    }
+    result.map_err(|e| IoError::Unsupported(e.to_string()))?;
+    Ok(warnings)
 }
 
 /// Write a native PSB to an already authorized seekable output. The caller owns atomic
 /// publication and cleanup; this never opens an ambient path.
 #[cfg(not(target_arch = "wasm32"))]
 pub fn export_psb_into<W: std::io::Write + std::io::Seek>(doc: &Document, out: &mut W, ctl: &photocraft_raster::Interrupt<'_>) -> Result<Vec<String>, IoError> {
-    psd_stream::export_into(doc, out, *ctl)
+    export_psb_into_with_options(doc, out, &ExportOptions { image_previews: false, ..Default::default() }, ctl)
+}
+
+/// Seekable PSB output honoring the same compatibility and preview settings as byte exports.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn export_psb_into_with_options<W: std::io::Write + std::io::Seek>(
+    doc: &Document,
+    out: &mut W,
+    opts: &ExportOptions,
+    ctl: &photocraft_raster::Interrupt<'_>,
+) -> Result<Vec<String>, IoError> {
+    psd_stream::export_into(doc, out, opts, *ctl)
 }
 
 /// Run `f` with an interrupt whose progress `0..=1` fills `lo..=hi` of `ctl`'s (same cancellation).
diff --git a/crates/io/src/psd_export.rs b/crates/io/src/psd_export.rs
index e2117b237e..f5c5e9e943 100644
--- a/crates/io/src/psd_export.rs
+++ b/crates/io/src/psd_export.rs
@@ -1369,9 +1369,9 @@ pub fn document_to_psd_with(doc: &Document, opts: &PsdExportOptions) -> (PsdFile
 }
 
 #[cfg(not(target_arch = "wasm32"))]
-pub(crate) fn stream_metadata(doc: &Document, opts: &PsdExportOptions) -> (PsdFile, Vec<String>, StreamSources) {
+pub(crate) fn stream_metadata(doc: &Document, opts: &PsdExportOptions, ctl: &Interrupt) -> (PsdFile, Vec<String>, StreamSources) {
     let mut sources = StreamSources::new();
-    let (file, warnings) = document_to_psd_nested(doc, opts, 0, &Interrupt::NONE, Some(&mut sources));
+    let (file, warnings) = document_to_psd_nested(doc, opts, 0, ctl, Some(&mut sources));
     (file, warnings, sources)
 }
 
@@ -1622,7 +1622,7 @@ fn document_to_psd_nested(
     // live nowhere else.
     let real_merged = opts.maximize_compatibility || ex.records.is_empty();
     let (mut planes, has_alpha) = if ex.deferred {
-        (Vec::new(), true)
+        (Vec::new(), real_merged)
     } else if real_merged {
         // Merged composite, rendered and encoded in bands (no full-size float composite). Matting
         // against white only changes pixels with alpha < 1; if some are slightly translucent but
diff --git a/crates/io/src/psd_stream.rs b/crates/io/src/psd_stream.rs
index c11a9e593b..3b303f614f 100644
--- a/crates/io/src/psd_stream.rs
+++ b/crates/io/src/psd_stream.rs
@@ -185,7 +185,12 @@ fn sink_error(e: std::io::Error) -> photocraft_psd::PsdError {
     photocraft_psd::PsdError::Invalid(format!("stream output: {e}"))
 }
 
-pub(crate) fn export_into<W: Write + Seek>(doc: &photocraft_doc::Document, out: &mut W, ctl: Interrupt<'_>) -> Result<Vec<String>, IoError> {
+pub(crate) fn export_into<W: Write + Seek>(
+    doc: &photocraft_doc::Document,
+    out: &mut W,
+    options: &crate::ExportOptions,
+    ctl: Interrupt<'_>,
+) -> Result<Vec<String>, IoError> {
     if !matches!(doc.mode, ColorMode::Rgb | ColorMode::Grayscale | ColorMode::Cmyk | ColorMode::Lab) {
         return Err(IoError::Unsupported("seekable PSB export requires RGB, Gray, CMYK or Lab".into()));
     }
@@ -218,8 +223,25 @@ pub(crate) fn export_into<W: Write + Seek>(doc: &photocraft_doc::Document, out:
         .saturating_add(metadata.saturating_mul(4))
         .saturating_add(embedded.saturating_mul(4));
     let _working = photocraft_raster::memory::try_reserve(working).map_err(IoError::Unsupported)?;
-    let opts = crate::psd_export::PsdExportOptions { force_psb: true, ..Default::default() };
-    let (file, warnings, sources) = crate::psd_export::stream_metadata(doc, &opts);
+    let opts = crate::psd_export::PsdExportOptions { force_psb: true, maximize_compatibility: options.psd_maximize_compatibility, ..Default::default() };
+    let (mut file, mut warnings, sources) = crate::with_span(&ctl, 0.0, 0.1, |ctl| crate::psd_export::stream_metadata(doc, &opts, ctl));
+    ctl.check().map_err(|_| IoError::Cancelled)?;
+    if !doc.metadata.text.is_empty() {
+        warnings.push("free-form text metadata is not supported by PSD/PSB; it will be dropped".into());
+    }
+    warnings.extend(crate::tiff_layers::strip_foreign_order_blocks(&mut file));
+    if options.image_previews {
+        match crate::psd_thumbnail::resource(doc) {
+            Ok(resource) => {
+                let at = file.resources.iter().position(|r| r.id == photocraft_psd::resources::ids::VERSION_INFO).unwrap_or(file.resources.len());
+                file.resources.insert(at, resource);
+            }
+            Err(e) => warnings.push(format!("image preview not saved: {e}")),
+        }
+    }
+    file.header.validate()?;
+    let merged_channels = fmt.mode.color_channels() + usize::from(file.merged_has_alpha());
+    let real_merged = options.psd_maximize_compatibility || file.layers().is_empty();
     let check = || -> photocraft_psd::Result<()> {
         if ctl.cancelled() {
             return Err(photocraft_psd::PsdError::Invalid("stream export cancelled".into()));
@@ -231,6 +253,7 @@ pub(crate) fn export_into<W: Write + Seek>(doc: &photocraft_doc::Document, out:
         out,
         |i, id, out| {
             check()?;
+            ctl.progress(0.15 + 0.35 * i as f32 / file.layers().len().max(1) as f32);
             let rec = file.layers().get(i).ok_or_else(|| photocraft_psd::PsdError::Invalid("missing output record".into()))?;
             let source = rec.layer_id().and_then(|id| sources.get(&id)).and_then(|(pixels, mask)| if id == -2 { mask.as_ref() } else { pixels.as_ref() });
             let r = rec.channel_rect(id);
@@ -270,9 +293,9 @@ pub(crate) fn export_into<W: Write + Seek>(doc: &photocraft_doc::Document, out:
             let cc = fmt.mode.color_channels();
             let white = photocraft_raster::from_rgba(&fmt, [1.0; 4]);
             let space = photocraft_compose::cmyk_space(doc);
-            photocraft_compose::render_bands(doc, doc.bounds(), 64, |band| -> photocraft_psd::Result<()> {
+            let mut write_band = |band: photocraft_compose::Buffer| -> photocraft_psd::Result<()> {
                 check()?;
-                let mut planes: Vec<Vec<u8>> = (0..=cc).map(|_| Vec::with_capacity(band.px.len() * fmt.sample.bytes())).collect();
+                let mut planes: Vec<Vec<u8>> = (0..merged_channels).map(|_| Vec::with_capacity(band.px.len() * fmt.sample.bytes())).collect();
                 photocraft_color::convert::with_cmyk_space(space.as_ref(), || {
                     let mut v = [0.0; 5];
                     for p in &band.px {
@@ -304,9 +327,22 @@ pub(crate) fn export_into<W: Write + Seek>(doc: &photocraft_doc::Document, out:
                 }
                 ctl.progress(0.5 + 0.5 * band.rect.y1 as f32 / doc.size.height.max(1) as f32);
                 Ok(())
-            })?;
-            for (i, channel) in doc.channels.iter().chain(doc.quick_mask.iter()).take(usize::from(file.header.channels).saturating_sub(cc + 1)).enumerate() {
-                let index = cc + 1 + i;
+            };
+            if real_merged {
+                photocraft_compose::render_bands(doc, doc.bounds(), 64, &mut write_band)?;
+            } else {
+                let mut y = 0;
+                while y < doc.size.height {
+                    let end = y.saturating_add(64).min(doc.size.height);
+                    let rect = Rect::from_xywh(0, y as i32, doc.size.width, end - y);
+                    write_band(photocraft_compose::Buffer { rect, px: vec![[1.0; 4]; doc.size.width as usize * (end - y) as usize] })?;
+                    y = end;
+                }
+            }
+            for (i, channel) in
+                doc.channels.iter().chain(doc.quick_mask.iter()).take(usize::from(file.header.channels).saturating_sub(merged_channels)).enumerate()
+            {
+                let index = merged_channels + i;
                 let mask_fmt = photocraft_color::PixelFormat::new(ColorMode::Grayscale, fmt.sample, false);
                 let converted = (channel.surface.format() != mask_fmt).then(|| channel.surface.convert(mask_fmt));
                 let surface = converted.as_ref().unwrap_or(&channel.surface);
diff --git a/crates/io/tests/streamed_save.rs b/crates/io/tests/streamed_save.rs
new file mode 100644
index 0000000000..252ba12b69
--- /dev/null
+++ b/crates/io/tests/streamed_save.rs
@@ -0,0 +1,102 @@
+#![cfg(not(target_arch = "wasm32"))]
+
+use photocraft_color::{ColorMode, SampleType};
+use photocraft_doc::{Document, Layer, Size};
+use photocraft_io::{ExportOptions, IoError, export_path_with_commit, needs_psb_stream};
+use photocraft_raster::Interrupt;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+struct TempRoot(std::path::PathBuf);
+impl TempRoot {
+    fn new() -> Self {
+        static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+        let nonce = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
+        let path = std::env::temp_dir().join(format!("photocraft-save-{}-{nonce}-{}", std::process::id(), NEXT.fetch_add(1, Ordering::Relaxed)));
+        std::fs::create_dir(&path).unwrap();
+        Self(path)
+    }
+    fn path(&self) -> &std::path::Path {
+        &self.0
+    }
+}
+impl Drop for TempRoot {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+fn document() -> Document {
+    let mut doc = Document::new("save", Size::new(32, 16), ColorMode::Rgb, SampleType::U16);
+    let mut layer = Layer::raster("pixels", doc.pixel_format());
+    layer.surface_mut().unwrap().fill_rect(doc.bounds(), &[0.25, 0.5, 0.75, 1.0]);
+    doc.layers.push(layer);
+    doc
+}
+
+#[test]
+fn all_native_formats_share_the_final_commit_boundary() {
+    let root = TempRoot::new();
+    let doc = document();
+    for ext in ["psb", "png"] {
+        let target = root.path().join(format!("document.{ext}"));
+        std::fs::write(&target, b"precious original").unwrap();
+        let result = export_path_with_commit(&doc, &target, &ExportOptions::default(), &Interrupt::NONE, || {
+            assert_eq!(std::fs::read(&target).unwrap(), b"precious original");
+            Err(IoError::Cancelled)
+        });
+        assert!(matches!(result, Err(IoError::Cancelled)));
+        assert_eq!(std::fs::read(&target).unwrap(), b"precious original");
+        assert_eq!(std::fs::read_dir(root.path()).unwrap().count(), if ext == "psb" { 1 } else { 2 });
+    }
+}
+
+#[test]
+fn cancellation_after_commit_does_not_report_a_published_save_as_failed() {
+    let root = TempRoot::new();
+    let doc = document();
+    for ext in ["psb", "png"] {
+        let target = root.path().join(format!("document.{ext}"));
+        let cancelled = AtomicBool::new(false);
+        let check = || cancelled.load(Ordering::Relaxed);
+        let interrupt = Interrupt::cancel_only(&check);
+        export_path_with_commit(&doc, &target, &ExportOptions::default(), &interrupt, || {
+            cancelled.store(true, Ordering::Relaxed);
+            Ok(())
+        })
+        .unwrap();
+        let reopened = photocraft_io::import_path_with("saved", &target, &Interrupt::NONE).unwrap();
+        assert_eq!(reopened.document.size, doc.size);
+    }
+}
+
+#[test]
+fn automatic_psd_size_promotion_uses_the_streaming_writer() {
+    let opts = ExportOptions::default();
+    let small = document();
+    assert!(!needs_psb_stream(&small, "small.PSD", &opts));
+    assert!(needs_psb_stream(&small, "small.PSB", &opts));
+    let sparse = Document::new("large", Size::new(30_000, 30_000), ColorMode::Rgb, SampleType::U8);
+    assert!(needs_psb_stream(&sparse, "large.psd", &opts));
+    assert!(!needs_psb_stream(&sparse, "large.png", &opts));
+}
+
+#[test]
+fn streaming_save_respects_compatibility_and_thumbnail_options() {
+    let doc = document();
+    for compatibility in [false, true] {
+        for previews in [false, true] {
+            let options = ExportOptions { psd_maximize_compatibility: compatibility, image_previews: previews, ..Default::default() };
+            let reference = photocraft_io::export(&doc, "reference.psb", &options).unwrap();
+            let reference = photocraft_psd::PsdFile::from_bytes(&reference.bytes).unwrap();
+            let mut output = std::io::Cursor::new(Vec::new());
+            photocraft_io::export_psb_into_with_options(&doc, &mut output, &options, &Interrupt::NONE).unwrap();
+            let output = photocraft_psd::PsdFile::from_bytes(output.get_ref()).unwrap();
+            assert_eq!(output.resources, reference.resources, "compatibility={compatibility}, previews={previews}");
+            let expected = reference.image_data.decode(&reference.header).unwrap();
+            let actual = output.image_data.decode(&output.header).unwrap();
+            // Streaming keeps a merged alpha plane for compatibility; the colour planes agree.
+            assert_eq!(&actual[..3], &expected[..3], "compatibility={compatibility}");
+            assert_eq!(output.layers().len(), reference.layers().len());
+        }
+    }
+}
diff --git a/crates/io/tests/streaming_psd.rs b/crates/io/tests/streaming_psd.rs
index 0a8038b3ac..1a9eca6b44 100644
--- a/crates/io/tests/streaming_psd.rs
+++ b/crates/io/tests/streaming_psd.rs
@@ -64,7 +64,8 @@ fn seekable_export_preserves_merged_layers_masks_and_unknown_metadata() {
             let input = photocraft_psd::testgen::layered(Version::Psb, mode, depth, Compression::ZipPrediction);
             let doc = photocraft_io::import("input", &input.to_bytes().unwrap()).unwrap().document;
             let (reference, _) = photocraft_io::document_to_psd_with(&doc, &photocraft_io::PsdExportOptions { force_psb: true, ..Default::default() });
-            photocraft_io::export_path_with(&doc, &path, &Default::default(), &Interrupt::NONE).unwrap();
+            photocraft_io::export_path_with(&doc, &path, &photocraft_io::ExportOptions { image_previews: false, ..Default::default() }, &Interrupt::NONE)
+                .unwrap();
             let output = photocraft_psd::PsdFile::from_bytes(&std::fs::read(&path).unwrap()).unwrap();
             assert_eq!(output.header, reference.header, "{mode:?}/{depth}");
             assert_eq!(output.resources, reference.resources);
diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs
index 10d050d5e4..7506e836a5 100644
--- a/crates/ui-egui/src/lib.rs
+++ b/crates/ui-egui/src/lib.rs
@@ -312,10 +312,13 @@ pub(crate) fn plain_raster(doc: &Document) -> Option<&photocraft_doc::Layer> {
 
 /// Encode a document: (file bytes, warnings about anything approximated or dropped).
 pub type ExportFn = Box<dyn Fn(&Document, &str, &ExportSettings) -> Result<(Vec<u8>, Vec<String>), String>>;
+/// Synchronous native path encoder, with bounded PSB output and owned atomic publication.
+pub type ExportPathFn = Box<dyn Fn(&Document, &str, &ExportSettings) -> Result<Vec<String>, String>>;
 pub type WriteFn = Box<dyn FnMut(&str, &[u8]) -> Result<(), String>>;
 /// Encode a document and write it to a path, reporting the stage to the job; returns the export
 /// warnings. Runs on a worker thread (see [`Services::save_file`]). It must call
-/// [`jobs_ui::SaveCtl::commit`] right before replacing the file, and write nothing if that fails.
+/// [`jobs_ui::SaveCtl::commit`] right before replacing the file. A rejected commit must retain
+/// the destination and remove any temporary created during encoding.
 pub type SaveFileFn = std::sync::Arc<dyn Fn(&Document, &str, &ExportSettings, &jobs_ui::SaveCtl) -> Result<Vec<String>, String> + Send + Sync>;
 
 /// Who a finished save serves.
@@ -408,6 +411,7 @@ pub struct Services {
     /// Background save over the automation write authority (`app.save`, #2017): same worker
     /// contract as `save_file`, but the bytes go through the capability-scoped workspace.
     pub automation_save: Option<SaveFileFn>,
+    pub export_path: Option<ExportPathFn>,
     /// Show an Open or Save dialog without waiting for it (see `file_dialog`).
     pub file_dialog: Option<FileDialogFn>,
     /// Write bytes to a path (native) or trigger a download (web).
@@ -421,6 +425,7 @@ pub struct Services {
     pub automation_import_path: Option<AutomationImportPathFn>,
     pub automation_write: Option<AutomationWriteFn>,
     pub automation_open_pcraft: Option<AutomationOpenPcraftFn>,
+    pub automation_export_path: Option<ExportPathFn>,
     pub automation_command: Option<AutomationCommandFn>,
     /// Same policy as [`Self::automation_command`], as a function pointer the engine calls for
     /// each step of `actions.play`. Installed on the session only while a control request or
@@ -1488,10 +1493,15 @@ impl PhotocraftApp {
         }
         let st = self.session.active().ok_or("no document")?;
         let (doc, revision) = (st.doc.id, st.revision);
-        let export = self.services.export.as_ref().ok_or("no exporter configured")?;
-        let (bytes, warnings) = export(&st.doc, &path, settings)?;
-        let write = self.services.write.as_mut().ok_or("no writer configured")?;
-        write(&path, &bytes)?;
+        let warnings = if let Some(export) = self.services.export_path.as_ref() {
+            export(&st.doc, &path, settings)?
+        } else {
+            let export = self.services.export.as_ref().ok_or("no exporter configured")?;
+            let (bytes, warnings) = export(&st.doc, &path, settings)?;
+            let write = self.services.write.as_mut().ok_or("no writer configured")?;
+            write(&path, &bytes)?;
+            warnings
+        };
         self.saved(doc, revision, &path, &warnings, copy);
         Ok(Some((path, warnings)))
     }
@@ -1602,10 +1612,15 @@ impl PhotocraftApp {
         let state = self.session.active().ok_or("no document")?;
         let (doc, revision) = (state.doc.id, state.revision);
         let settings = ExportSettings { tga_bits, ..self.save_settings() };
-        let export = self.services.export.as_ref().ok_or("no exporter configured")?;
-        let (bytes, warnings) = export(&state.doc, &target, &settings)?;
-        let write = self.services.automation_write.as_mut().ok_or("automation write authority is not configured")?;
-        write(&target, &bytes)?;
+        let warnings = if let Some(export) = self.services.automation_export_path.as_ref() {
+            export(&state.doc, &target, &settings)?
+        } else {
+            let export = self.services.export.as_ref().ok_or("no exporter configured")?;
+            let (bytes, warnings) = export(&state.doc, &target, &settings)?;
+            let write = self.services.automation_write.as_mut().ok_or("automation write authority is not configured")?;
+            write(&target, &bytes)?;
+            warnings
+        };
         self.saved_automation(doc, revision, &target, &warnings, false);
         Ok(reply(&target, &warnings))
     }
diff --git a/crates/ui-egui/src/save_identity_tests.rs b/crates/ui-egui/src/save_identity_tests.rs
index c947afc9b6..ea6ca8a63d 100644
--- a/crates/ui-egui/src/save_identity_tests.rs
+++ b/crates/ui-egui/src/save_identity_tests.rs
@@ -30,6 +30,43 @@ fn identity(app: &PhotocraftApp) -> (String, Option<String>, u64, u64) {
     (st.doc.name.clone(), st.path.clone(), st.revision, st.saved_revision)
 }
 
+#[test]
+fn synchronous_path_save_records_identity_only_after_success() {
+    let mut app = app();
+    let before = identity(&app);
+    app.background_jobs = false;
+    app.services.export = Some(Box::new(|_, _, _| panic!("path save must not use the byte exporter")));
+    app.services.write = Some(Box::new(|_, _| panic!("path save owns its atomic writer")));
+    app.services.export_path = Some(Box::new(|_, _, _| Err("cancelled before publication".into())));
+    assert!(app.save_as(Some("saved.psb".into())).is_err());
+    assert_eq!(identity(&app), before);
+    app.services.export_path = Some(Box::new(|_, path, _| {
+        assert_eq!(path, "saved.psb");
+        Ok(Vec::new())
+    }));
+    app.save_as(Some("saved.psb".into())).unwrap();
+    let st = app.session.active().unwrap();
+    assert_eq!(st.path.as_deref(), Some("saved.psb"));
+    assert!(!st.is_dirty());
+}
+
+#[test]
+fn automation_path_save_is_synchronous_and_uses_only_its_authorized_service() {
+    let mut app = app();
+    app.background_jobs = true;
+    app.services.export = Some(Box::new(|_, _, _| panic!("must not materialize output bytes")));
+    app.services.export_path = Some(Box::new(|_, _, _| panic!("automation must not use ambient output authority")));
+    app.services.automation_write = Some(Box::new(|_, _| panic!("authorized stream owns publication")));
+    app.services.automation_export_path = Some(Box::new(|_, path, _| {
+        assert_eq!(path, "agent.psb");
+        Ok(Vec::new())
+    }));
+    let result = app.save_automation(Some("agent.psb".into())).unwrap();
+    assert_eq!(result["path"], "agent.psb");
+    assert!(!app.session.has_jobs());
+    assert!(!app.session.active().unwrap().is_dirty());
+}
+
 #[test]
 fn new_document_psd_and_subsequent_save_as_adopt_the_written_file_name() {
     for depth in [8, 16, 32] {
diff --git a/docs/roadmap.md b/docs/roadmap.md
index dca334cfe0..52d9fec5d7 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -128,3 +128,5 @@ Each milestone has a **definition of done (DoD)** and must leave `main` green on
 2026-10-13: seekable native PSD/PSB and supported scanline EXR imports decode bounded bands at the original resolution. Authorized opens retain read-only source protection. See [native streaming I/O](streaming-io.md).
 
 2026-10-13: large canvases render visible original-resolution pages with bounded RAM/VRAM, cancellable workers and stale-result rejection; the new upstream background redraw remains available for full-canvas paths. See [GPU streaming](streaming-gpu.md).
+
+2026-10-13: native interactive and authorized saves share the save service, bounded PSB encoding and atomic publication. Upstream progress, copy and OpenRaster save semantics are retained. See [streaming saves](streaming-save.md).
diff --git a/docs/streaming-io.md b/docs/streaming-io.md
index 3cc4d3a674..481f728b52 100644
--- a/docs/streaming-io.md
+++ b/docs/streaming-io.md
@@ -27,8 +27,7 @@ document without a source save path.
 The seekable output API accepts a caller-owned writer; atomic path output encodes into a temporary
 file beside the destination, syncs it using the shared platform helper, then renames it. Encoder
 failure, cancellation or unwinding removes the temporary and preserves the old destination. Its
-integration with the desktop background-save service is a separate change, using upstream's
-`SaveCtl` and document-lock/saved-revision contract.
+integration with the desktop background-save service is documented in [streamed saves](streaming-save.md).
 
 Synthetic tests compare streamed import with the byte decoder across PSD/PSB versions, depths,
 colour modes and compression, and verify masks, metadata, cancellation, EXR chunk handling,
diff --git a/docs/streaming-save.md b/docs/streaming-save.md
new file mode 100644
index 0000000000..1fd95d16c0
--- /dev/null
+++ b/docs/streaming-save.md
@@ -0,0 +1,27 @@
+# Streamed native saves
+
+Native PSB output uses the background-save service shared by the desktop UI. The service holds
+upstream's Arc snapshot and document lock, reports band progress, and records the saved revision
+on the original document even when the active tab changes. Same-destination exclusion, worker
+completion, and close/quit handling remain those of the upstream save jobs.
+
+The encoder creates and owns a temporary file beside the destination, writes original-depth
+channel bands, and flushes the file before calling `SaveCtl.commit()`. This final boundary runs
+immediately before atomic replacement. Failure or cancellation before the boundary preserves the
+existing destination and removes the temporary. After commit, a late cancellation cannot turn a
+successful publication into a reported failure. PSD output that exceeds the PSD size limit also
+uses this PSB writer.
+
+Synchronous interactive saves use the same native path encoder. Automation `app.save` uses
+upstream's background-save service when available, and retains a synchronous fallback. Both use
+only the session's held write-directory capability, including the temporary output and atomic
+rename. The background stream checks cancellation before publication through `SaveCtl.commit()`.
+Other formats retain their checked byte encoders while sharing the atomic publication boundary.
+
+Streaming PSB saves respect the Maximize Compatibility and Image Previews settings, including
+the placeholder merged image when compatibility is disabled and optional PSD thumbnails.
+
+Synthetic regressions exercise precommit rejection, late cancellation, automatic PSD promotion,
+tab switching during a native background save, saved identity, and authorized-path rejection.
+The integration builds on the save implementation merged in
+[PR #2072](https://github.com/storytold/photocraft/pull/2072).

From a8845f37cac9a4ad1209a971641251912c38a934 Mon Sep 17 00:00:00 2001
From: Daktyl198 <2475672+Daktyl198@users.noreply.github.com>
Date: Wed, 14 Oct 2026 06:14:20 +0000
Subject: [PATCH 004/109] Actions: a recorded Save As or Save for Web with the
 suggested name saves each document under its own (#5305)

Keeping the name Save As or Save for Web suggests records only the folder
(and Save As's extension), so playing the action saves each document under
its own name in that folder, as in Photoshop. A name typed in is still
recorded as typed. Before, every played document was written over the one
recorded file.

Save for Web takes a `folder` param for this, and .atn export writes it as
a "save in directory" step that imports back.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 crates/engine/src/atn_cmds.rs                 | 13 ++++-
 crates/engine/src/atn_cmds/tests.rs           |  4 ++
 crates/engine/src/web_cmds.rs                 | 10 ++--
 crates/engine/src/web_cmds/tests.rs           | 21 ++++++++
 crates/ui-egui/src/actions.rs                 | 39 ++++++++++++++
 .../src/discard_ui/tests/targa_tests.rs       | 34 +++++++++++++
 crates/ui-egui/src/file_ui.rs                 | 48 ++++++++++++++++-
 crates/ui-egui/src/lib.rs                     | 51 +++++++++++++++++--
 crates/ui-egui/src/targa_options_ui.rs        | 11 +++-
 crates/ui-egui/src/tiff_options_ui.rs         |  8 ++-
 10 files changed, 224 insertions(+), 15 deletions(-)

diff --git a/crates/engine/src/atn_cmds.rs b/crates/engine/src/atn_cmds.rs
index 391c21abd8..3cb8743652 100644
--- a/crates/engine/src/atn_cmds.rs
+++ b/crates/engine/src/atn_cmds.rs
@@ -1718,7 +1718,8 @@ fn export_from(d: &Descriptor) -> Mapped {
     let unsupported = Mapped::Unsupported { harmless: false };
     let Some(u) = get_obj(d, "Usng") else { return unsupported };
     let Some(path) = d.get("In  ").and_then(path_text) else { return unsupported };
-    let mut p = json!({"path": path});
+    // "Save in directory": `In  ` is only the folder, and each document saves under its own name.
+    let mut p = if get_bool(u, "DIDr") == Some(true) { json!({"folder": path}) } else { json!({"path": path}) };
     if let Some(f) = get_enum(u, "Fmt ") {
         match lookup(WEB_FORMATS, &f) {
             Some(f) => p["format"] = json!(f),
@@ -1745,8 +1746,16 @@ fn export_from(d: &Descriptor) -> Mapped {
 }
 
 fn export_to(_: &str, p: &Value) -> Option<Descriptor> {
-    let path = jstr(p, "path")?;
+    // A step recorded with the document's own name keeps only its folder (#5305).
+    let (path, in_folder) = match (jstr(p, "path").filter(|v| !v.is_empty()), jstr(p, "folder")) {
+        (Some(path), _) => (path, false),
+        (None, Some(folder)) => (folder, true),
+        (None, None) => return None,
+    };
     let mut u = desc("SaveForWeb").with("Op  ", enm("SWOp", "OpSa")).with("Fmt ", enm("IRFm", lookup_back(WEB_FORMATS, jstr(p, "format").unwrap_or("png24"))?));
+    if in_folder {
+        u = u.with("DIDr", D::Boolean(true));
+    }
     for (key, param, default) in [
         ("Intr", "interlaced", false),
         ("Trns", "transparency", true),
diff --git a/crates/engine/src/atn_cmds/tests.rs b/crates/engine/src/atn_cmds/tests.rs
index bdb839fa30..17e550e3f2 100644
--- a/crates/engine/src/atn_cmds/tests.rs
+++ b/crates/engine/src/atn_cmds/tests.rs
@@ -277,6 +277,10 @@ fn every_mapped_command_exports_and_imports_back() {
             "file.export.saveForWebLegacy",
             json!({"path": "/tmp/out/banner.png", "format": "png24", "interlaced": false, "transparency": true, "embedIcc": false, "progressive": false, "optimized": true, "matte": "#ffffff"}),
         ),
+        (
+            "file.export.saveForWebLegacy",
+            json!({"folder": "/tmp/out", "format": "png24", "interlaced": false, "transparency": true, "embedIcc": false, "progressive": false, "optimized": true, "matte": "#ffffff"}),
+        ),
         (
             "file.export.saveForWebLegacy",
             json!({"path": "C:\\shots\\a.jpg", "format": "jpeg", "interlaced": false, "transparency": false, "embedIcc": true, "progressive": true, "optimized": true, "quality": 80, "matte": "none"}),
diff --git a/crates/engine/src/web_cmds.rs b/crates/engine/src/web_cmds.rs
index 595ad21956..f8eda6eb34 100644
--- a/crates/engine/src/web_cmds.rs
+++ b/crates/engine/src/web_cmds.rs
@@ -848,7 +848,7 @@ pub fn save_for_web_with_writer(s: &mut Session, p: &Value, write: &mut dyn FnMu
 fn remember_web_settings(s: &mut Session, cmd: &str, settings: &Value) {
     let mut m = settings.clone();
     if let Some(o) = m.as_object_mut() {
-        for k in ["path", "dir", "trustedSliceHtml"] {
+        for k in ["path", "dir", "folder", "trustedSliceHtml"] {
             o.remove(k);
         }
     }
@@ -885,7 +885,11 @@ fn save_for_web_impl(s: &mut Session, p: &Value, write: &mut dyn FnMut(&str, &[u
             _ => true,
         })
         .collect();
-    let single = p.get("path").and_then(Value::as_str).filter(|v| !v.is_empty());
+    // `folder` (with no `path`): the whole image into that folder under the document's own name,
+    // so an action recorded with the suggested name saves each document it is played on under
+    // that document's name, as in Photoshop (#5305).
+    let in_folder = p.get("folder").and_then(Value::as_str).map(|f| join(f, &format!("{}.{}", slices::base_name(&doc), st.format.ext())));
+    let single = p.get("path").and_then(Value::as_str).filter(|v| !v.is_empty()).or(in_folder.as_deref());
     let dir = p.get("dir").and_then(Value::as_str).filter(|v| !v.is_empty());
     let mut last_web = p.clone();
     // A trusted-markup decision applies to this export only, never to another document opened
@@ -1468,7 +1472,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Save for Web (Legacy)…",
             &["File", "Export"],
             Some("Cmd+Alt+Shift+S"),
-            r##"{"preset":"GIF 128 Dithered|JPEG High|PNG-24|…"?,"format":"gif|png8|png24|jpeg|wbmp"="png24","palette":"perceptual|selective|adaptive|restrictive|exact|systemMac|systemWindows|uniform"="selective","colors":2..256=256,"colorTable":["#rrggbb",…]? (fixed opaque source palette, 1–256 entries; 255 with transparency),"colorTableEdits":{"0":"#rrggbb",…}? (replace entries after indexing; requires colorTable),"dither":"none|diffusion|pattern|noise"="diffusion","ditherAmount":0..100=88,"transparency":bool=true,"matte":"#rrggbb|none"="none" (a preset's own: white; formats without transparency go over white),"interlaced":bool=false,"webSnap":0..100=0,"quality":0..100=60,"progressive":bool=false,"optimized":bool=true,"embedIcc":bool=false,"metadata":"none|copyright|copyrightAndContact|all"="copyright","convertToSrgb":bool=true,"width"|"height"|"percent"? (image size),"resample":"bicubic|bilinear|nearest"?,"path":file? (whole image),"dir":folder? (one file per slice in images/),"imagesFolder":relative-folder?="images","html":bool=false,"trustedSliceHtml":bool=false (only for trusted documents; emit raw no-image cell HTML),"slices":"all|user"="all","numbers":[n]?} → no path/dir: {bytes,width,height,colors,colorTable,transparentIndex} estimate; else {files, html, bytes}"##,
+            r##"{"preset":"GIF 128 Dithered|JPEG High|PNG-24|…"?,"format":"gif|png8|png24|jpeg|wbmp"="png24","palette":"perceptual|selective|adaptive|restrictive|exact|systemMac|systemWindows|uniform"="selective","colors":2..256=256,"colorTable":["#rrggbb",…]? (fixed opaque source palette, 1–256 entries; 255 with transparency),"colorTableEdits":{"0":"#rrggbb",…}? (replace entries after indexing; requires colorTable),"dither":"none|diffusion|pattern|noise"="diffusion","ditherAmount":0..100=88,"transparency":bool=true,"matte":"#rrggbb|none"="none" (a preset's own: white; formats without transparency go over white),"interlaced":bool=false,"webSnap":0..100=0,"quality":0..100=60,"progressive":bool=false,"optimized":bool=true,"embedIcc":bool=false,"metadata":"none|copyright|copyrightAndContact|all"="copyright","convertToSrgb":bool=true,"width"|"height"|"percent"? (image size),"resample":"bicubic|bilinear|nearest"?,"path":file? (whole image),"folder":folder? (whole image, named after the document; ignored with "path"),"dir":folder? (one file per slice in images/),"imagesFolder":relative-folder?="images","html":bool=false,"trustedSliceHtml":bool=false (only for trusted documents; emit raw no-image cell HTML),"slices":"all|user"="all","numbers":[n]?} → no path/dir: {bytes,width,height,colors,colorTable,transparentIndex} estimate; else {files, html, bytes}"##,
             has_doc,
             save_for_web
         ),
diff --git a/crates/engine/src/web_cmds/tests.rs b/crates/engine/src/web_cmds/tests.rs
index c3ffe6edce..bc17a87993 100644
--- a/crates/engine/src/web_cmds/tests.rs
+++ b/crates/engine/src/web_cmds/tests.rs
@@ -714,3 +714,24 @@ fn overlapping_slices_keep_the_later_slice_in_html() {
 
 #[path = "color_table_tests.rs"]
 mod color_table_tests;
+
+/// #5305: `folder` writes the whole image there under the document's own name, so an action
+/// recorded with the suggested name saves each document it is played on under that name; it is
+/// a destination, never a remembered setting.
+#[test]
+fn folder_saves_under_the_documents_own_name() {
+    let dir = tmp("folder_own_name");
+    let mut s = session(8);
+    let r = s.execute("file.export.saveForWebLegacy", json!({"folder": dir, "format": "png24"})).unwrap();
+    let first = format!("{dir}/web.png");
+    assert_eq!(r["files"], json!([first]));
+    assert_eq!(decode(&first).dimensions(), (64, 48));
+    assert!(s.prefs().dialogs.get("file.export.saveForWebLegacy").is_some_and(|m| m.get("folder").is_none()));
+    s.execute("file.new", json!({"width": 8, "height": 4, "name": "second.psd"})).unwrap();
+    let r = s.execute("file.export.saveForWebLegacy", json!({"folder": dir, "format": "jpeg"})).unwrap();
+    assert_eq!(r["files"], json!([format!("{dir}/second.jpg")]));
+    // A `path` wins over `folder`.
+    let r = s.execute("file.export.saveForWebLegacy", json!({"path": format!("{dir}/named.png"), "folder": dir, "format": "png24"})).unwrap();
+    assert_eq!(r["files"], json!([format!("{dir}/named.png")]));
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/ui-egui/src/actions.rs b/crates/ui-egui/src/actions.rs
index e0f3713f2e..c5fb8f21c6 100644
--- a/crates/ui-egui/src/actions.rs
+++ b/crates/ui-egui/src/actions.rs
@@ -1290,6 +1290,45 @@ mod tests {
         assert_eq!(app.session.active().unwrap().path.as_deref(), Some("out/result.psd"));
     }
 
+    /// #5305: a Save As recorded with the document's own name (the one Save As suggests) keeps
+    /// only the folder, so playing the action saves each document under its own name instead of
+    /// over the recorded file; a name typed in is recorded as it is.
+    #[test]
+    fn recorded_save_as_with_the_suggested_name_saves_each_document_under_its_own() {
+        let written = std::rc::Rc::new(std::cell::RefCell::new(Vec::<String>::new()));
+        let log = written.clone();
+        let services = crate::Services {
+            export: Some(Box::new(|doc, path, _| {
+                photocraft_io::export(doc, path, &Default::default()).map(|r| (r.bytes, r.warnings)).map_err(|e| e.to_string())
+            })),
+            write: Some(Box::new(move |path, _| {
+                log.borrow_mut().push(path.to_string());
+                Ok(())
+            })),
+            ..Default::default()
+        };
+        let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), services);
+        let ctx = egui::Context::default();
+        app.run("file.new", json!({"width": 16, "height": 16, "name": "first"})).unwrap();
+        app.run("actions.record", json!({})).unwrap();
+        crate::menus::invoke(&mut app, &ctx, "file.saveAs", json!({"path": "out/first.psd"})).unwrap();
+        crate::menus::invoke(&mut app, &ctx, "file.saveAs", json!({"path": "out/renamed.psd"})).unwrap();
+        app.run("actions.stop", json!({})).unwrap();
+        let steps = &app.session.actions.list[0].steps;
+        assert_eq!(steps, &[("file.saveAs".into(), json!({"folder": "out", "extension": "psd"})), ("file.saveAs".into(), json!({"path": "out/renamed.psd"}))]);
+        // Played on another document: its own name in the recorded folder, then the typed name.
+        app.session.actions.list[0].steps.truncate(1);
+        written.borrow_mut().clear();
+        app.run("file.new", json!({"width": 16, "height": 16, "name": "second"})).unwrap();
+        let played = app.run("actions.play", json!({"action": 0})).unwrap();
+        assert!(played.get("failed").is_none(), "{played}");
+        let second = std::path::Path::new("out").join("second.psd").to_string_lossy().into_owned();
+        assert_eq!(*written.borrow(), std::slice::from_ref(&second));
+        assert_eq!(app.session.active().unwrap().path.as_deref(), Some(second.as_str()));
+        // A folder step needs its extension.
+        assert!(app.replay_save("file.saveAs", &json!({"folder": "out"})).is_err());
+    }
+
     #[test]
     fn set_folders_group_actions_and_collapse() {
         use egui_kittest::{Harness, kittest::Queryable};
diff --git a/crates/ui-egui/src/discard_ui/tests/targa_tests.rs b/crates/ui-egui/src/discard_ui/tests/targa_tests.rs
index 565fe01037..17a83e79bd 100644
--- a/crates/ui-egui/src/discard_ui/tests/targa_tests.rs
+++ b/crates/ui-egui/src/discard_ui/tests/targa_tests.rs
@@ -182,6 +182,40 @@ fn recorded_targa_save_as_keeps_its_bits_and_replays_without_asking() {
     );
 }
 
+/// #5305: a Targa Save As answered in Targa Options with the document's own name records only the
+/// folder and extension (with the bits), so playback saves each document under its own name; a
+/// Save a Copy keeps its path.
+#[test]
+fn recorded_targa_save_as_with_the_documents_name_keeps_only_the_folder() {
+    let (mut h, writes) = targa_app(false, "copy.tga");
+    let ctx = h.ctx.clone();
+    let name = h.state().session.active().unwrap().doc.name.clone();
+    h.state_mut().run("actions.record", json!({})).unwrap();
+    h.state_mut().save_as(Some(format!("out/{name}.tga"))).unwrap();
+    h.run_steps(2);
+    h.get_by_label("OK").click();
+    h.run_steps(3);
+    crate::menus::invoke(h.state_mut(), &ctx, "file.saveACopy", json!({})).unwrap();
+    h.run_steps(3);
+    h.key_press(Key::Enter);
+    h.run_steps(3);
+    h.state_mut().run("actions.stop", json!({})).unwrap();
+    let steps = &h.state().session.actions.list[0].steps;
+    assert_eq!(
+        steps,
+        &[
+            ("file.saveAs".into(), json!({"folder": "out", "extension": "tga", "tgaBits": 24})),
+            ("file.saveACopy".into(), json!({"path": "copy.tga", "tgaBits": 24}))
+        ]
+    );
+    writes.borrow_mut().clear();
+    h.state_mut().run("file.new", json!({"width": 8, "height": 8, "name": "second"})).unwrap();
+    let played = h.state_mut().run("actions.play", json!({"action": 0})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    let second = std::path::Path::new("out").join("second.tga").to_string_lossy().into_owned();
+    assert_eq!(writes.borrow().as_slice(), &[(second, asked(Some(24))), ("copy.tga".to_string(), asked(Some(24)))]);
+}
+
 /// Closing an unsaved document whose save goes to a Targa waits behind Targa Options, then closes.
 #[test]
 fn closing_after_a_targa_save_waits_for_targa_options() {
diff --git a/crates/ui-egui/src/file_ui.rs b/crates/ui-egui/src/file_ui.rs
index c3b8abc4d7..54959db40b 100644
--- a/crates/ui-egui/src/file_ui.rs
+++ b/crates/ui-egui/src/file_ui.rs
@@ -218,7 +218,7 @@ pub fn open_web(app: &mut PhotocraftApp) -> u64 {
         .unwrap_or_else(|| json!({"format": "jpeg", "quality": 60}));
     if let Value::Object(m) = last {
         for (k, v) in m {
-            if !matches!(k.as_str(), "path" | "dir" | "width" | "height" | "percent" | "colorTable" | "colorTableEdits") {
+            if !matches!(k.as_str(), "path" | "dir" | "folder" | "width" | "height" | "percent" | "colorTable" | "colorTableEdits") {
                 f.insert(k, v);
             }
         }
@@ -669,7 +669,7 @@ fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Result<Value,
         authorize(&prepared)?;
         p = prepared;
     }
-    if p.get("path").is_some() || p.get("dir").is_some() {
+    if p.get("path").is_some() || p.get("dir").is_some() || p.get("folder").is_some() {
         return save_for_web(app, p);
     }
     let doc = app.session.active().ok_or("no document")?.doc.clone();
@@ -684,6 +684,10 @@ fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Result<Value,
             let dir = path.rfind(['/', '\\']).map(|i| path[..i].to_string()).unwrap_or_else(|| ".".into());
             p["dir"] = json!(dir);
             p["html"] = json!(html);
+        } else if let Some(folder) = kept_name_folder(&path, &base, st.format.ext()) {
+            // The suggested name kept: only the folder, so a recorded action saves each
+            // document under its own name, as in Photoshop (#5305).
+            p["folder"] = json!(folder);
         } else {
             p["path"] = json!(path);
         }
@@ -691,6 +695,14 @@ fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Result<Value,
     })
 }
 
+/// The folder of `path` when its file is the one Save for Web suggests: `base`, with the format's
+/// own extension `ext` (the folder alone writes exactly that file).
+fn kept_name_folder(path: &str, base: &str, ext: &str) -> Option<String> {
+    let file = std::path::Path::new(path);
+    let kept = file.file_stem().is_some_and(|s| s.to_string_lossy() == base) && file.extension().is_some_and(|e| e.to_string_lossy().eq_ignore_ascii_case(ext));
+    kept.then(|| file.parent().map(|d| d.to_string_lossy().into_owned()).unwrap_or_default())
+}
+
 /// Runs Save for Web with `p`, which says where to write.
 fn save_for_web(app: &mut PhotocraftApp, p: Value) -> Result<Value, String> {
     #[cfg(target_arch = "wasm32")]
@@ -1218,6 +1230,38 @@ mod tests {
         assert_eq!(f["colors"], 64);
     }
 
+    /// #5305: Save for Web with the suggested name runs (and so is recorded) with only the
+    /// folder, so an action saves each document under its own name; another name is kept.
+    #[test]
+    fn save_for_web_with_the_suggested_name_records_only_the_folder() {
+        let dir = std::env::temp_dir().join(format!("pc-webui-kept-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        for (name, expected) in [
+            ("web.png", json!({"folder": dir.to_string_lossy()})),
+            ("other.png", json!({"path": dir.join("other.png").to_string_lossy()})),
+            ("web.gif", json!({"path": dir.join("web.gif").to_string_lossy()})),
+        ] {
+            let (mut app, ctx) = app();
+            let target = dir.join(name).to_string_lossy().into_owned();
+            let (dialog, _) = crate::file_dialog::fake(vec![Some(crate::file_dialog::FileDialogAnswer::SaveTo(target.clone()))]);
+            app.services.file_dialog = Some(dialog);
+            let id = open_web(&mut app);
+            app.ui.dialog_mut(id).unwrap().fields.insert("format".into(), json!("png24"));
+            crate::dialogs::confirm(&mut app, id).unwrap();
+            app.poll_file_dialog(&ctx, None);
+            assert!(std::path::Path::new(&target).exists(), "{target}");
+            let (id, params) = app.session.journal.last().unwrap();
+            assert_eq!(id, WEB_COMMAND);
+            for (k, v) in expected.as_object().unwrap() {
+                assert_eq!(&params[k], v, "{params}");
+            }
+            assert!(params.get(if name == "web.png" { "path" } else { "folder" }).is_none(), "{params}");
+            assert!(!dir.join("web.png").exists() || name == "web.png", "only the picked file is written");
+            let _ = std::fs::remove_file(&target);
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
     #[test]
     fn save_for_web_starts_at_the_current_document_size() {
         let (mut app, _) = app();
diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs
index 38118955c3..14a8ca33b4 100644
--- a/crates/ui-egui/src/lib.rs
+++ b/crates/ui-egui/src/lib.rs
@@ -1390,8 +1390,8 @@ impl PhotocraftApp {
     /// Writes the Save As and journals it as a `file.saveAs` step with its path (and TIFF or
     /// Targa answer), so an action being recorded keeps it (#2032).
     fn save_as_step(&mut self, path: String, tiff_layers: Option<bool>, tga_bits: Option<photocraft_io::TgaBits>) -> Result<Value, String> {
-        let r = self.write_save(path.clone(), tiff_layers, tga_bits)?;
-        let mut step = serde_json::json!({"path": path});
+        let mut step = self.save_as_record(&path);
+        let r = self.write_save(path, tiff_layers, tga_bits)?;
         if let Some(layers) = tiff_layers {
             step["tiffLayers"] = layers.into();
         }
@@ -1402,6 +1402,48 @@ impl PhotocraftApp {
         Ok(r)
     }
 
+    /// The `file.saveAs` step that records a Save As of the active document to `path`, taken
+    /// before the save renames the document. With the document's own name kept (the name Save
+    /// As suggests), only the folder and the extension are recorded, so the action saves each
+    /// document it is played on under that document's name, as in Photoshop (#5305); a name
+    /// typed in is recorded as it is.
+    pub(crate) fn save_as_record(&self, path: &str) -> Value {
+        let file = std::path::Path::new(path);
+        let kept = self.own_file_stem().is_some_and(|own| file.file_stem().is_some_and(|s| s.to_string_lossy() == own));
+        match (kept, file.extension()) {
+            (true, Some(ext)) => {
+                let folder = file.parent().map(|d| d.to_string_lossy().into_owned()).unwrap_or_default();
+                serde_json::json!({"folder": folder, "extension": ext.to_string_lossy()})
+            }
+            _ => serde_json::json!({"path": path}),
+        }
+    }
+
+    /// The name Save As suggests for the active document, without its extension: its file's,
+    /// or its own for a document never saved ("Untitled" for one with no name).
+    fn own_file_stem(&self) -> Option<String> {
+        let st = self.session.active()?;
+        let source = st.path.as_deref().unwrap_or(&st.doc.name);
+        let stem = std::path::Path::new(source).file_stem().map(|s| s.to_string_lossy().into_owned()).filter(|s| !s.is_empty());
+        Some(stem.unwrap_or_else(|| "Untitled".into()))
+    }
+
+    /// The file a recorded `file.saveAs` step writes: its `path`, or for a step recorded with
+    /// the document's own name, that folder and extension with the active document's name.
+    fn recorded_save_path(&self, params: &Value) -> Result<String, String> {
+        if let Some(path) = params.get("path").and_then(Value::as_str).filter(|p| !p.is_empty()) {
+            return Ok(path.to_string());
+        }
+        let (Some(folder), Some(ext)) =
+            (params.get("folder").and_then(Value::as_str), params.get("extension").and_then(Value::as_str).filter(|e| !e.is_empty()))
+        else {
+            return Err("Save As needs a `path`, or a `folder` and an `extension`".into());
+        };
+        let stem = self.own_file_stem().ok_or("no document")?;
+        let name = format!("{stem}.{ext}");
+        Ok(if folder.is_empty() { name } else { std::path::Path::new(folder).join(name).to_string_lossy().into_owned() })
+    }
+
     /// Replays a recorded `file.save` / `file.saveAs` / `file.saveACopy` step: no dialog or prompt, and the
     /// recorded TIFF or Targa answer (if any) stands in for the TIFF or Targa Options prompt.
     pub(crate) fn replay_save(&mut self, id: &str, params: &Value) -> Result<Value, String> {
@@ -1416,14 +1458,15 @@ impl PhotocraftApp {
                 )?;
             return self.save_in_place(path);
         }
-        let path = params.get("path").and_then(Value::as_str).filter(|p| !p.is_empty()).ok_or("Save As needs a `path`")?;
         let tga_bits = targa_options_ui::bits_param(params, id)?;
         if id == "file.saveACopy" {
+            let path = params.get("path").and_then(Value::as_str).filter(|p| !p.is_empty()).ok_or("Save a Copy needs a `path`")?;
             // A copy: the document keeps its own file and unsaved state, as when recorded (#4373).
             let doc = self.session.active().ok_or("no document")?.doc.clone();
             return crate::view_cmds::write_copy(self, &doc, path, tga_bits);
         }
-        self.save_as_step(path.to_string(), params.get("tiffLayers").and_then(Value::as_bool), tga_bits)
+        let path = self.recorded_save_path(params)?;
+        self.save_as_step(path, params.get("tiffLayers").and_then(Value::as_bool), tga_bits)
     }
 
     /// What a save writes by default under the preferences: File Handling › Image Previews
diff --git a/crates/ui-egui/src/targa_options_ui.rs b/crates/ui-egui/src/targa_options_ui.rs
index c2161a0c9b..66d3a544b4 100644
--- a/crates/ui-egui/src/targa_options_ui.rs
+++ b/crates/ui-egui/src/targa_options_ui.rs
@@ -79,8 +79,15 @@ pub fn show(app: &mut PhotocraftApp, ctx: &egui::Context) {
     if ok || ctx.input_mut(|i| i.consume_key(egui::Modifiers::NONE, egui::Key::Enter)) {
         let Some(p) = app.targa_options.take() else { return };
         let settings = ExportSettings { tga_bits: Some(p.bits), ..app.save_settings() };
-        let step = serde_json::json!({"path": p.path, "tgaBits": p.bits.bits()});
-        let written = app.with_document(p.doc, |app| app.write_document(p.path, &settings, p.copy));
+        let mut step = serde_json::json!({"path": p.path});
+        let written = app.with_document(p.doc, |app| {
+            // A Save As keeps the document's own name as only its folder (#5305); a copy its path.
+            if p.record == "file.saveAs" {
+                step = app.save_as_record(&p.path);
+            }
+            app.write_document(p.path, &settings, p.copy)
+        });
+        step["tgaBits"] = p.bits.bits().into();
         if written.is_ok() {
             // An action being recorded keeps the Save As or Save a Copy with this answer (#2032).
             app.session.journal.push((p.record.into(), step));
diff --git a/crates/ui-egui/src/tiff_options_ui.rs b/crates/ui-egui/src/tiff_options_ui.rs
index febd5964cb..b63e3be452 100644
--- a/crates/ui-egui/src/tiff_options_ui.rs
+++ b/crates/ui-egui/src/tiff_options_ui.rs
@@ -71,8 +71,12 @@ pub fn show(app: &mut PhotocraftApp, ctx: &egui::Context) {
             app.session.edit_prefs(|prefs| prefs.file_handling.ask_before_saving_layered_tiff = false);
         }
         let settings = ExportSettings { tiff_layers: !p.discard_layers, ..app.save_settings() };
-        let step = serde_json::json!({"path": p.path, "tiffLayers": !p.discard_layers});
-        let written = app.with_document(p.doc, |app| app.write_document(p.path, &settings, p.discard_layers));
+        let mut step = serde_json::Value::Null;
+        let written = app.with_document(p.doc, |app| {
+            step = app.save_as_record(&p.path);
+            app.write_document(p.path, &settings, p.discard_layers)
+        });
+        step["tiffLayers"] = (!p.discard_layers).into();
         if written.is_ok() {
             // An action being recorded keeps the Save As with this answer (#2032).
             app.session.journal.push(("file.saveAs".into(), step));

From 4e3c151ba1f0d1cba4c4b0fdfca88f327fd23f00 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Thu, 22 Oct 2026 14:26:00 -0700
Subject: [PATCH 005/109] Actions: recorded Check Spelling steps play on the
 targeted type layer

When an action records a step whose `layer` names the only selected
layer, recording drops `layer`, and the step plays on the layer that is
targeted at playback (#7262). `edit.checkSpelling` handled a missing
`layer` in two other ways. `change` required a numeric `layer`, so a
recorded Change from the Check Spelling dialog or the canvas menu
stopped playback with "`change` needs `layer`" and left the text
unchanged. `list` and `changeAll` check every type layer when neither
`layer` nor `allLayers` is given, so a recorded `changeAll` that named
the selected layer played on every type layer.

`change` now takes its layer from `layer` (an id or a name) or else the
active layer, as `type.insertText` does. When recording drops `layer`
from an `edit.checkSpelling` step, it also records `"allLayers": false`.
---
 crates/engine/src/layer_multi_cmds.rs |  6 +++-
 crates/engine/src/type_spell_cmds.rs  | 45 +++++++++++++++++++++++++--
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/crates/engine/src/layer_multi_cmds.rs b/crates/engine/src/layer_multi_cmds.rs
index 83d4e815a2..a3b1d5ff66 100644
--- a/crates/engine/src/layer_multi_cmds.rs
+++ b/crates/engine/src/layer_multi_cmds.rs
@@ -123,7 +123,8 @@ pub(crate) fn recorded_selection(s: &Session, mut p: Value) -> Value {
 /// For `layer.select`, captures the layer by name. For other commands, if a numeric `layer`
 /// parameter references the document's sole selected layer, normalises it to the target form
 /// (omitting `layer`) so that the recorded step applies to whatever layer is targeted when
-/// replayed or exported to `.atn` (#7248).
+/// replayed or exported to `.atn` (#7248). When it drops `layer` from an `edit.checkSpelling` step,
+/// it also records `"allLayers": false`.
 pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Option<&[LayerId]>) -> Value {
     if id == "layer.select" {
         return recorded_selection(s, p);
@@ -137,6 +138,9 @@ pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Optio
         let mut p = p;
         if let Some(fields) = p.as_object_mut() {
             fields.remove("layer");
+            if id == "edit.checkSpelling" {
+                fields.insert("allLayers".into(), json!(false));
+            }
         }
         return p;
     }
diff --git a/crates/engine/src/type_spell_cmds.rs b/crates/engine/src/type_spell_cmds.rs
index d42500c722..6ae2182e47 100644
--- a/crates/engine/src/type_spell_cmds.rs
+++ b/crates/engine/src/type_spell_cmds.rs
@@ -117,7 +117,7 @@ fn list(s: &Session, p: &Value) -> Result<Value> {
 /// Replaces one occurrence (verified to still be `word` when given).
 fn change(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "edit.checkSpelling";
-    let id = LayerId(p.get("layer").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `layer`"))?);
+    let id = layer_param(s, p)?;
     let start = p.get("start").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `start`"))? as usize;
     let end = p.get("end").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `end`"))? as usize;
     let to = p.get("replace").and_then(Value::as_str).ok_or_else(|| bad(cmd, "`change` needs `replace`"))?.to_string();
@@ -270,7 +270,7 @@ pub fn specs() -> Vec<CommandSpec> {
             label: "Check Spelling…",
             menu: &["Edit"],
             shortcut: None,
-            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer","start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"}"#,
+            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer"? (default: the active layer),"start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"}"#,
             enabled: has_type,
             journal: true,
             run: check_spelling,
@@ -369,6 +369,47 @@ mod tests {
         assert_eq!(r["correct"], false);
     }
 
+    #[test]
+    fn change_without_layer_edits_the_active_type_layer() {
+        let (mut s, id) = session("Teh end");
+        let r = s.execute("edit.checkSpelling", json!({"action": "change", "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
+        assert_eq!((r["layer"].as_u64(), r["end"].as_u64()), (Some(id), Some(3)));
+        assert_eq!(text_of(&s, id), "The end");
+    }
+
+    #[test]
+    fn recorded_change_on_the_selected_layer_plays_on_another_document() {
+        let (mut s, id) = session("Teh end");
+        s.execute("actions.record", json!({"name": "Spell"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        assert_eq!(text_of(&s, id), "The end");
+        // The recorded step names no layer, so it acts on the layer targeted when it plays.
+        assert!(s.actions.list[0].steps[0].1.get("layer").is_none(), "{:?}", s.actions.list[0].steps);
+        s.execute("file.new", json!({"width": 300, "height": 100, "background": "white"})).unwrap();
+        let other = s.execute("type.create", json!({"x": 10, "y": 50, "text": "Teh end", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+        let r = s.execute("actions.play", json!({"action": "Spell"})).unwrap();
+        assert!(r.get("failed").is_none(), "{r}");
+        assert_eq!(r["ran"], 1);
+        assert_eq!(text_of(&s, other), "The end");
+    }
+
+    #[test]
+    fn recorded_change_all_on_the_selected_layer_plays_on_that_layer_only() {
+        let (mut s, a) = session("teh one");
+        let b = s.execute("type.create", json!({"x": 10, "y": 90, "text": "teh two", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+        s.execute("layer.select", json!({"layer": a})).unwrap();
+        s.execute("actions.record", json!({"name": "All"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "changeAll", "layer": a, "word": "teh", "replace": "the"})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        assert_eq!((text_of(&s, a).as_str(), text_of(&s, b).as_str()), ("the one", "teh two"));
+        s.execute("edit.undo", json!({})).unwrap();
+        s.execute("layer.select", json!({"layer": a})).unwrap();
+        let r = s.execute("actions.play", json!({"action": "All"})).unwrap();
+        assert!(r.get("failed").is_none(), "{r}");
+        assert_eq!((text_of(&s, a).as_str(), text_of(&s, b).as_str()), ("the one", "teh two"));
+    }
+
     #[test]
     fn disabled_without_type() {
         let mut s = Session::new();

From 289cbc6ce0a339886500941ff76233a8f7561ff0 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sat, 24 Oct 2026 14:49:50 -0700
Subject: [PATCH 006/109] Layers panel: the filter row lists linked, missing or
 embedded smart objects

The filter-type dropdown gains Smart Object, with three toggles: smart
objects linked to a file, linked to a file that was not there when the
app last looked, and embedded. Like the Kind toggles, the filter applies
once a toggle is on, and the panel lists the smart objects that match any
toggle that is on.

The two-second look at linked files now also records which files were
not there, and Session::missing_links returns them for the active
document. ui.set {layerFilter} takes by: "smartObject" and a smart list.
---
 crates/automation/src/server.rs             |   7 +-
 crates/engine/src/lib.rs                    |   3 +
 crates/engine/src/link_watch.rs             |  48 +++++++++
 crates/ui-egui/src/control.rs               |  25 +++++
 crates/ui-egui/src/layer_filter_ui.rs       |  95 +++++++++++++++---
 crates/ui-egui/src/layer_filter_ui_tests.rs | 102 +++++++++++++++++++-
 crates/ui-egui/src/panels.rs                |   2 +-
 crates/ui-egui/src/state.rs                 |   4 +
 docs/control-protocol.md                    |   2 +-
 docs/ui-parity.md                           |   3 +-
 10 files changed, 270 insertions(+), 21 deletions(-)

diff --git a/crates/automation/src/server.rs b/crates/automation/src/server.rs
index f5ccef00c7..449325d1fc 100644
--- a/crates/automation/src/server.rs
+++ b/crates/automation/src/server.rs
@@ -346,9 +346,10 @@ pub struct UiSetParams {
     /// dashes, dashOffset and opacity; null disables the stroke). Shape stroke fields use
     /// `shape.edit` names and units; colour comes from `tools.setColors`. camTransformOnDrop (bool,
     /// the Content-Aware Move tool's Transform On Drop). tileGrid (bool, a developer overlay of the
-    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name" or
-    /// "mode"), kinds (a list of layer kinds), name (matches part of the layer name) and mode (a
-    /// blend mode name) for the Layers panel filter). strokeTrace (true, false, "stderr" or "off":
+    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name", "mode" or
+    /// "smartObject"), kinds (a list of layer kinds), name (matches part of the layer name), mode
+    /// (a blend mode name) and smart (a list of "linked", "missing" and "embedded") for the Layers
+    /// panel filter). strokeTrace (true, false, "stderr" or "off":
     /// the stroke latency trace at runtime; a CSV file is set at launch with --stroke-trace, not
     /// over this channel). updatesOpen (bool, the Help › Check for Updates window). Other fields
     /// are an error.
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 44cbe903ad..3e79faa0a7 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -537,6 +537,9 @@ pub struct Session {
     pub link_stamps: std::collections::HashMap<(u64, String), link_watch::Stamp>,
     /// The stamps being taken on a worker thread ([`Session::start_link_scan`]).
     pub link_scan: Option<link_watch::LinkScan>,
+    /// Each open document's linked smart objects' files that were not there when last looked at
+    /// ([`Session::missing_links`]).
+    link_missing: std::collections::HashSet<(u64, String)>,
     /// Select Subject's last result, reused while the pixels are unchanged (#2865).
     subject_cache: smartselect_cmds::SubjectCache,
     /// Object Selection's Object Finder results (#4087), shared by the hover preview and the
diff --git a/crates/engine/src/link_watch.rs b/crates/engine/src/link_watch.rs
index 453af7806b..acbcfed472 100644
--- a/crates/engine/src/link_watch.rs
+++ b/crates/engine/src/link_watch.rs
@@ -108,6 +108,30 @@ impl Session {
         }
     }
 
+    /// The active document's linked files that were not there at the last look (the Layers
+    /// panel's Missing filter). A path that is not followed ([`crate::doc_path`]) is never looked
+    /// at, so it is not listed.
+    pub fn missing_links(&self) -> HashSet<String> {
+        let Some(doc) = self.active().map(|d| d.doc.id.0) else { return HashSet::new() };
+        self.link_missing.iter().filter(|(d, _)| *d == doc).map(|(_, p)| p.clone()).collect()
+    }
+
+    /// Remember which of document `doc`'s files in `now` were not there, and forget the files of
+    /// closed documents. The web app has no files to look at, so it lists none.
+    fn note_missing_links(&mut self, doc: u64, now: &[(String, Vec<u64>, Option<Stamp>)]) {
+        let open: HashSet<u64> = self.documents().iter().map(|d| d.doc.id.0).collect();
+        self.link_missing.retain(|(d, _)| *d != doc && open.contains(d));
+        if cfg!(target_arch = "wasm32") {
+            return;
+        }
+        let document = self.active().and_then(|st| st.path.clone());
+        for (path, _, stamp) in now {
+            if stamp.is_none() && crate::doc_path::resolve_in(path, document.as_deref().map(std::path::Path::new)).is_ok() {
+                self.link_missing.insert((doc, path.clone()));
+            }
+        }
+    }
+
     /// Apply a finished look (`None` while there is none, or it is still running).
     pub fn poll_link_scan(&mut self) -> Option<Result<Value>> {
         let (doc, stamps) = self.link_scan.as_ref()?.lock().unwrap_or_else(PoisonError::into_inner).take()?;
@@ -122,6 +146,7 @@ impl Session {
         if self.active().map(|d| d.doc.id.0) != Some(doc) {
             return Ok(json!({"updated": []}));
         }
+        self.note_missing_links(doc, &now);
         // A background job holds the document: refreshing now would replace the snapshot it works
         // on and its result would be discarded. The stamps stay as they were, so the change is
         // seen again by the first look after the job ends.
@@ -282,6 +307,29 @@ mod tests {
         assert!(is(centre(&s), BLUE));
     }
 
+    #[test]
+    fn a_look_lists_the_linked_files_that_are_not_there() {
+        let d = dir("missing");
+        let path = d.join("art.png");
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, _) = placed(&path);
+        let stored = super::linked_files(&s.active().unwrap().doc)[0].0.clone();
+        assert!(s.missing_links().is_empty(), "nothing looked at yet");
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert!(s.missing_links().is_empty());
+        std::fs::remove_file(&path).unwrap();
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert_eq!(s.missing_links(), [stored.clone()].into());
+        // Only the document's own files: another one in front lists none.
+        s.execute("file.new", json!({"width": 10, "height": 10})).unwrap();
+        assert!(s.missing_links().is_empty());
+        s.set_active(0);
+        assert_eq!(s.missing_links(), [stored].into());
+        std::fs::write(&path, png(10, 10, "#0000ff")).unwrap();
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert!(s.missing_links().is_empty(), "the file is back");
+    }
+
     #[test]
     fn a_background_look_updates_changed_files() {
         let d = dir("scan");
diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs
index b85427c6fa..4ebf90ea39 100644
--- a/crates/ui-egui/src/control.rs
+++ b/crates/ui-egui/src/control.rs
@@ -2041,6 +2041,31 @@ mod tests {
         assert!(app.ui.tool_options.gradient_classic, "invalid mode must not change options");
     }
 
+    /// The Layers panel's Smart Object filter takes a list of its toggles.
+    #[test]
+    fn ui_set_drives_the_layers_panel_smart_object_filter() {
+        use crate::layer_filter_ui::FilterBy;
+        let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+        let ctx = egui::Context::default();
+        let ok = call(&mut app, &ctx, "ui.set", json!({"layerFilter": {"by": "smartObject", "smart": ["missing", "embedded", "missing"]}}));
+        assert_eq!(ok["ok"], true, "{ok}");
+        assert_eq!(app.ui.layer_filter_by, FilterBy::SmartObject);
+        assert_eq!(app.ui.layer_filter_smart, ["missing", "embedded"], "toggles are kept once each");
+        let ok = call(&mut app, &ctx, "ui.set", json!({"layerFilter": {"smart": []}}));
+        assert_eq!(ok["ok"], true, "{ok}");
+        assert!(app.ui.layer_filter_smart.is_empty());
+        for bad in [
+            json!({"layerFilter": {"smart": ["library"]}}),
+            json!({"layerFilter": {"smart": "linked"}}),
+            json!({"layerFilter": {"by": "kind", "smart": [1]}}),
+            json!({"layerFilter": {"by": "smart"}}),
+        ] {
+            let r = call(&mut app, &ctx, "ui.set", bad.clone());
+            assert_eq!(r["ok"], false, "{bad} → {r}");
+            assert_eq!((app.ui.layer_filter_by, app.ui.layer_filter_smart.len()), (FilterBy::SmartObject, 0), "{bad} changed nothing");
+        }
+    }
+
     /// #5048: the Layers panel filter is drivable; a bad field changes nothing.
     #[test]
     fn ui_set_drives_the_layers_panel_filter() {
diff --git a/crates/ui-egui/src/layer_filter_ui.rs b/crates/ui-egui/src/layer_filter_ui.rs
index e933d0c165..0c727aa0a8 100644
--- a/crates/ui-egui/src/layer_filter_ui.rs
+++ b/crates/ui-egui/src/layer_filter_ui.rs
@@ -1,10 +1,12 @@
 //! The Layers panel's filter row (#5048): a filter-type dropdown, as in Photoshop, then the
 //! controls for that type. Kind toggles layer kinds, Name matches part of the layer name, Mode
-//! picks one blend mode. The criteria live in `UiState` (`layer_filter*`), so the control channel
-//! can read and set them.
+//! picks one blend mode, Smart Object toggles linked, missing and embedded smart objects. The
+//! criteria live in `UiState` (`layer_filter*`), so the control channel can read and set them.
+
+use std::collections::HashSet;
 
 use photocraft_color::BlendMode;
-use photocraft_doc::{Layer, LayerContent};
+use photocraft_doc::{Layer, LayerContent, SmartSource};
 use serde::{Deserialize, Serialize};
 
 use crate::state::UiState;
@@ -18,6 +20,7 @@ pub enum FilterBy {
     Kind,
     Name,
     Mode,
+    SmartObject,
 }
 
 /// The filter criteria, copied out of `UiState` for one frame of the Layers panel.
@@ -28,20 +31,43 @@ pub struct Filter {
     /// As typed; matched trimmed and ignoring case.
     pub name: String,
     pub mode: BlendMode,
+    /// The Smart Object toggles that are on, from [`SMART`].
+    pub smart: Vec<String>,
+    /// The linked files the Smart Object filter's Missing toggle lists
+    /// ([`photocraft_engine::Session::missing_links`]).
+    pub missing: HashSet<String>,
 }
 
 impl Filter {
     pub fn of(ui: &UiState) -> Self {
-        Self { by: ui.layer_filter_by, kinds: ui.layer_filter.clone(), name: ui.layer_filter_name.clone(), mode: ui.layer_filter_mode }
+        Self {
+            by: ui.layer_filter_by,
+            kinds: ui.layer_filter.clone(),
+            name: ui.layer_filter_name.clone(),
+            mode: ui.layer_filter_mode,
+            smart: ui.layer_filter_smart.clone(),
+            missing: HashSet::new(),
+        }
+    }
+
+    /// [`Filter::of`] `app`'s settings, with the active document's missing linked files while
+    /// the panel filters by Smart Object.
+    pub fn of_app(app: &PhotocraftApp) -> Self {
+        let mut f = Self::of(&app.ui);
+        if f.by == FilterBy::SmartObject {
+            f.missing = app.session.missing_links();
+        }
+        f
     }
 
     /// Whether the panel is filtered. Like Photoshop, Mode always filters (by Normal at first);
-    /// Kind and Name only once a kind is toggled or some text is typed.
+    /// Kind, Name and Smart Object only once a toggle is on or some text is typed.
     pub fn active(&self) -> bool {
         match self.by {
             FilterBy::Kind => !self.kinds.is_empty(),
             FilterBy::Name => !self.name.trim().is_empty(),
             FilterBy::Mode => true,
+            FilterBy::SmartObject => !self.smart.is_empty(),
         }
     }
 
@@ -54,6 +80,14 @@ impl Filter {
             FilterBy::Kind => self.kinds.iter().any(|k| k == kind(l)),
             FilterBy::Name => l.name.to_lowercase().contains(&self.name.trim().to_lowercase()),
             FilterBy::Mode => l.blend == self.mode,
+            FilterBy::SmartObject => {
+                let LayerContent::Smart(sm) = &l.content else { return false };
+                self.smart.iter().any(|k| match (k.as_str(), &sm.source) {
+                    ("linked", SmartSource::Linked { .. }) | ("embedded", SmartSource::Embedded { .. }) => true,
+                    ("missing", SmartSource::Linked { path }) => self.missing.contains(path),
+                    _ => false,
+                })
+            }
         }
     }
 }
@@ -61,18 +95,22 @@ impl Filter {
 /// The kinds the Kind filter toggles.
 pub const KINDS: [&str; 5] = ["pixel", "adjustment", "type", "shape", "smart"];
 
-/// `ui.set {layerFilter: {by?, kinds?, name?, mode?}}`: `current` with the given fields replaced,
-/// or an error naming the bad field (nothing changes then). `by` is `kind`, `name` or `mode`;
-/// `kinds` a list of [`KINDS`]; `mode` a blend mode name such as `Multiply` or `Pass Through`.
+/// The Smart Object filter's toggles: smart objects linked to a file, linked to a file that is
+/// not there, and embedded in the document.
+pub const SMART: [&str; 3] = ["linked", "missing", "embedded"];
+
+/// `ui.set {layerFilter: {by?, kinds?, name?, mode?, smart?}}`: `current` with the given fields
+/// replaced, or an error naming the bad field (nothing changes then). `by` is `kind`, `name`,
+/// `mode` or `smartObject`; `kinds` a list of [`KINDS`]; `mode` a blend mode name such as
+/// `Multiply` or `Pass Through`; `smart` a list of [`SMART`].
 pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, String> {
     let Some(o) = v.as_object() else { return Err("layerFilter must be an object".into()) };
-    if let Some(k) = o.keys().find(|k| !["by", "kinds", "name", "mode"].contains(&k.as_str())) {
-        return Err(format!("unknown layerFilter field `{k}` (fields: by, kinds, name, mode)"));
+    if let Some(k) = o.keys().find(|k| !["by", "kinds", "name", "mode", "smart"].contains(&k.as_str())) {
+        return Err(format!("unknown layerFilter field `{k}` (fields: by, kinds, name, mode, smart)"));
     }
-    let mut f =
-        Filter { by: current.layer_filter_by, kinds: current.layer_filter.clone(), name: current.layer_filter_name.clone(), mode: current.layer_filter_mode };
+    let mut f = Filter::of(current);
     if let Some(by) = o.get("by") {
-        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name or mode".to_string())?;
+        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name, mode or smartObject".to_string())?;
     }
     if let Some(kinds) = o.get("kinds") {
         let list = kinds.as_array().ok_or("layerFilter.kinds must be a list")?;
@@ -95,6 +133,18 @@ pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, Strin
             .filter(|m| *m == BlendMode::PassThrough || BlendMode::LAYER_MODES.contains(m))
             .ok_or_else(|| format!("layerFilter.mode: unknown blend mode `{name}`"))?;
     }
+    if let Some(smart) = o.get("smart") {
+        let list = smart.as_array().ok_or("layerFilter.smart must be a list")?;
+        f.smart = Vec::new();
+        for k in list {
+            let Some(k) = k.as_str().filter(|k| SMART.contains(k)) else {
+                return Err(format!("layerFilter.smart: unknown toggle {k} (toggles: {})", SMART.join(", ")));
+            };
+            if !f.smart.iter().any(|have| have == k) {
+                f.smart.push(k.to_string());
+            }
+        }
+    }
     Ok(f)
 }
 
@@ -104,6 +154,7 @@ pub fn apply(ui: &mut UiState, f: Filter) {
     ui.layer_filter = f.kinds;
     ui.layer_filter_name = f.name;
     ui.layer_filter_mode = f.mode;
+    ui.layer_filter_smart = f.smart;
 }
 
 /// The kind filter's name for `l`'s content ("" for groups, which no kind matches).
@@ -122,7 +173,7 @@ fn kind(l: &Layer) -> &'static str {
 pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     ui.horizontal(|ui| {
         ui.spacing_mut().item_spacing.x = 2.0;
-        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode"))];
+        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode")), (FilterBy::SmartObject, tl!("Smart Object"))];
         widgets::dropdown(ui, "layer-filter-by", &mut app.ui.layer_filter_by, &by, 64.0);
         ui.add_space(4.0);
         match app.ui.layer_filter_by {
@@ -153,6 +204,22 @@ pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
                 let width = ui.available_width().max(96.0);
                 widgets::dropdown(ui, "layer-filter-mode", &mut app.ui.layer_filter_mode, &modes, width);
             }
+            FilterBy::SmartObject => {
+                for (kind, icon, tip) in [
+                    ("linked", "link", tl!("Filter for smart objects linked locally")),
+                    ("missing", "unlink", tl!("Filter for linked smart objects that are missing")),
+                    ("embedded", "file", tl!("Filter for embedded smart objects")),
+                ] {
+                    let on = app.ui.layer_filter_smart.iter().any(|k| k == kind);
+                    if icons::button(ui, icon, 22.0, on, tip).clicked() {
+                        if on {
+                            app.ui.layer_filter_smart.retain(|k| k != kind);
+                        } else {
+                            app.ui.layer_filter_smart.push(kind.to_string());
+                        }
+                    }
+                }
+            }
         }
     });
 }
diff --git a/crates/ui-egui/src/layer_filter_ui_tests.rs b/crates/ui-egui/src/layer_filter_ui_tests.rs
index aeeb63e7cc..5f30052010 100644
--- a/crates/ui-egui/src/layer_filter_ui_tests.rs
+++ b/crates/ui-egui/src/layer_filter_ui_tests.rs
@@ -1,4 +1,4 @@
-//! #5048: the Layers panel's filter-type dropdown (Kind, Name, Mode).
+//! #5048: the Layers panel's filter-type dropdown (Kind, Name, Mode, Smart Object).
 
 use egui::vec2;
 use egui_kittest::Harness;
@@ -135,3 +135,103 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
     h.run_steps(4);
     assert_eq!(drawn(&h), ["ink notes"]);
 }
+
+/// A PNG at `<temp>/<name>/art.png` (a folder per test: tests run in parallel).
+fn art_file(name: &str) -> std::path::PathBuf {
+    let d = std::env::temp_dir().join(format!("photocraft-layer-filter-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&d);
+    std::fs::create_dir_all(&d).unwrap();
+    let file = d.join("art.png");
+    let mut s = photocraft_engine::Session::new();
+    s.execute("file.new", json!({"width": 8, "height": 8, "background": "#ff0000"})).unwrap();
+    s.execute("file.saveACopy", json!({"path": file.to_string_lossy(), "layers": false})).unwrap();
+    file
+}
+
+/// "Linked art" (linked to `file`) above "Embedded art" (a copy of `file`), "Plain" and
+/// "Background".
+fn smart_session(file: &std::path::Path) -> photocraft_engine::Session {
+    let mut s = photocraft_engine::Session::new();
+    s.execute("file.new", json!({"width": 32, "height": 32})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Plain"})).unwrap();
+    for (command, name) in [("file.placeEmbedded", "Embedded art"), ("file.placeLinked", "Linked art")] {
+        s.execute(command, json!({"path": file.to_string_lossy()})).unwrap();
+        let id = s.active().unwrap().active_layer.unwrap().0;
+        s.execute("layer.setProps", json!({"layer": id, "name": name})).unwrap();
+    }
+    s
+}
+
+fn by_smart(smart: &[&str], missing: std::collections::HashSet<String>) -> Filter {
+    Filter { smart: smart.iter().map(|k| k.to_string()).collect(), missing, ..filter(FilterBy::SmartObject, &[], "", BlendMode::Normal) }
+}
+
+#[test]
+fn the_smart_object_filter_lists_linked_missing_and_embedded_smart_objects() {
+    let file = art_file("list");
+    let mut s = smart_session(&file);
+    let doc = &s.active().unwrap().doc;
+    let none = std::collections::HashSet::new;
+    assert!(!by_smart(&[], none()).active(), "no toggle on: every layer");
+    assert_eq!(listed(doc, &by_smart(&[], none())), ["Linked art", "Embedded art", "Plain", "Background"]);
+    assert_eq!(listed(doc, &by_smart(&["linked"], none())), ["Linked art"]);
+    assert_eq!(listed(doc, &by_smart(&["embedded"], none())), ["Embedded art"]);
+    assert_eq!(listed(doc, &by_smart(&["linked", "embedded"], none())), ["Linked art", "Embedded art"]);
+    assert_eq!(listed(doc, &by_smart(&["missing"], s.missing_links())), Vec::<String>::new(), "the file is there");
+    std::fs::remove_file(&file).unwrap();
+    s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+    let doc = &s.active().unwrap().doc;
+    assert_eq!(listed(doc, &by_smart(&["missing"], s.missing_links())), ["Linked art"]);
+    assert_eq!(listed(doc, &by_smart(&["missing", "embedded"], s.missing_links())), ["Linked art", "Embedded art"]);
+}
+
+#[test]
+fn saved_settings_without_the_smart_object_toggles_still_load() {
+    let mut saved = serde_json::to_value(UiState::default()).unwrap();
+    assert!(saved.as_object_mut().unwrap().remove("layer_filter_smart").is_some(), "layer_filter_smart is saved");
+    let ui: UiState = serde_json::from_value(saved).unwrap();
+    assert!(ui.layer_filter_smart.is_empty());
+    let round =
+        serde_json::to_value(UiState { layer_filter_by: FilterBy::SmartObject, layer_filter_smart: vec!["missing".into()], ..UiState::default() }).unwrap();
+    let back: UiState = serde_json::from_value(round.clone()).unwrap();
+    assert_eq!(
+        (round["layer_filter_by"].as_str(), back.layer_filter_by, back.layer_filter_smart),
+        (Some("smartObject"), FilterBy::SmartObject, vec!["missing".to_string()])
+    );
+}
+
+#[test]
+fn the_smart_object_toggles_filter_the_panel() {
+    let file = art_file("panel");
+    let session = smart_session(&file);
+    let mut h = Harness::builder().with_size(vec2(1440.0, 900.0)).with_max_steps(64).build_eframe(move |cc| {
+        PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());
+        PhotocraftApp::new(session, crate::Services::default())
+    });
+    h.run_steps(8);
+    let all = ["Linked art", "Embedded art", "Plain", "Background"];
+    assert_eq!(drawn(&h), all);
+    h.get_by_value("Kind").click();
+    h.run_steps(4);
+    h.query_all_by_label("Smart Object").last().expect("Smart Object in the open list").click();
+    h.run_steps(4);
+    assert_eq!(h.state().ui.layer_filter_by, FilterBy::SmartObject);
+    assert_eq!(drawn(&h), all, "no toggle on yet: every layer");
+    h.get_by_label("Filter for embedded smart objects").click();
+    h.run_steps(4);
+    assert_eq!(h.state().ui.layer_filter_smart, ["embedded"]);
+    assert_eq!(drawn(&h), ["Embedded art"]);
+    h.get_by_label("Filter for embedded smart objects").click();
+    h.get_by_label("Filter for smart objects linked locally").click();
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["Linked art"]);
+    h.get_by_label("Filter for smart objects linked locally").click();
+    h.get_by_label("Filter for linked smart objects that are missing").click();
+    h.run_steps(4);
+    assert_eq!(h.state().ui.layer_filter_smart, ["missing"]);
+    assert_eq!(drawn(&h), Vec::<String>::new(), "the file is there");
+    std::fs::remove_file(&file).unwrap();
+    h.state_mut().session.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["Linked art"]);
+}
diff --git a/crates/ui-egui/src/panels.rs b/crates/ui-egui/src/panels.rs
index b6bd34d9d2..f8dc2b563b 100644
--- a/crates/ui-egui/src/panels.rs
+++ b/crates/ui-egui/src/panels.rs
@@ -2714,7 +2714,7 @@ fn layers(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
                 ui.scroll_with_delta(vec2(0.0, delta));
                 ctx.request_repaint();
             }
-            let filter = crate::layer_filter_ui::Filter::of(&app.ui);
+            let filter = crate::layer_filter_ui::Filter::of_app(app);
             let fx_collapsed = app.session.active().map(|d| d.fx_collapsed.clone()).unwrap_or_default();
             crate::layer_row_ui::begin(ui.ctx());
             // The drawn rows, top to bottom (#1721): the space between them and below the last
diff --git a/crates/ui-egui/src/state.rs b/crates/ui-egui/src/state.rs
index b3b9d7b05e..4917103ac1 100644
--- a/crates/ui-egui/src/state.rs
+++ b/crates/ui-egui/src/state.rs
@@ -1477,6 +1477,9 @@ pub struct UiState {
     /// Layers panel kind filter ("pixel", "adjustment", "type", "shape", "smart"); empty = all.
     #[serde(default)]
     pub layer_filter: Vec<String>,
+    /// Layers panel Smart Object filter ("linked", "missing", "embedded"); empty = all.
+    #[serde(default)]
+    pub layer_filter_smart: Vec<String>,
     /// Thumbnail dimensions, content cropping and filter-strip visibility.
     #[serde(default)]
     pub layers_panel_options: LayersPanelOptions,
@@ -1666,6 +1669,7 @@ impl Default for UiState {
             artboard_tool: Default::default(),
             shell: Default::default(),
             layer_filter: Vec::new(),
+            layer_filter_smart: Vec::new(),
             layers_panel_options: LayersPanelOptions::default(),
             layers_panel_dialog: None,
             layer_filter_by: Default::default(),
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 3d4d601b30..d01354e803 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -54,7 +54,7 @@ The transport is `apps/photocraft/src/control_server.rs`, and the handlers are i
 - `ui.set` also accepts `camTransformOnDrop` (boolean), the Content-Aware Move tool's Transform On Drop checkbox: a drop then puts a scale/rotate box on the patch (`ui.inspect` › `camTransform`: its document/revision, drag `offset` and `frame`), driven with `ui.pointer` (handles as Free Transform's; outside the box rotates), committed with `ui.key Enter` (one `paint.contentAwareMove` with `scaleX`, `scaleY`, `rotate`) or dropped with `Escape`.
 - `ui.set` also accepts `tileGrid` (boolean), a developer overlay of the active layer's storage tiles: the tile grid over the document, every stored tile filled and labelled `tx,ty`, tiles with identical pixels in a shared colour and unique ones in blue. It has no menu item and View › Extras doesn't hide it. `ui.inspect` reports it as `view.tile_grid`.
 - `ui.set` also accepts `strokeTrace` (`true`, `false`, `"stderr"` or `"off"`): turn the stroke latency trace on or off at runtime; each stroke's summary is in `ui.inspect` `perf.strokeTrace`. A CSV file of every frame is set only at launch (`PHOTOCRAFT_STROKE_TRACE=<file.csv>` / `--stroke-trace <file.csv>`): the control channel doesn't write files outside the automation write root
-- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?}`, any subset. `by` is `kind`, `name` or `mode` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`). Kind and Name filter only once a kind is on or text is typed; Mode always filters, by Normal at first, as in Photoshop. Fields left out keep their value; a bad one is an error and changes nothing.
+- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?, smart?}`, any subset. `by` is `kind`, `name`, `mode` or `smartObject` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`); `smart` lists the Smart Object toggles that are on (`linked`: linked to a file, `missing`: linked to a file that was not there when the app last looked, `embedded`). Kind, Name and Smart Object filter only once a toggle is on or text is typed; Mode always filters, by Normal at first, as in Photoshop. Fields left out keep their value; a bad one is an error and changes nothing.
 - Each painting tool keeps its own brush, as in Photoshop: `tools.setBrush` and `ui.set {brushSize}` change the active tool's brush, and switching tools swaps in that tool's own (size, hardness, mode, opacity, flow, dynamics, smoothing). A tool used for the first time starts from the brush in hand. The colours, the erase flag and the stroke seed stay shared. So `ui.set {tool: "eraser", brushSize: 12}` sets the Eraser's size, and `ui.set {tool: "brush"}` afterwards brings the Brush's own size back.
 - Brush Pose's `pose.overrideTiltX` and `pose.overrideTiltY` are independent booleans. For example, `engine.execute {"command":"tools.setBrush","params":{"pose":{"enabled":true,"tiltX":45,"overrideTiltX":true,"overrideTiltY":false}}}` fixes X at 45° while Y follows the stylus. Pose tilts are degrees (±90); the Brush Settings panel displays percentages (±100). Old stored `overrideTilt` values migrate to both axes. In command patches, `overrideTilt` sets both axes unless an explicit axis field in the same patch overrides it. `brush.get` includes both axis flags and the legacy combined readback (`overrideTilt` is true only when both flags are true). Axis-only journals omit that derived combined key so replay retains the other axis. Present flag values must be booleans; null and other types return an error.
 - `ui.set` also accepts the Eyedropper options bar (#1649): `eyedropperSampleSize` (`"point"` or 1, 3, 5, 11, 31, 51, 101: the side of the averaged square, shared by the Eyedropper, a painting tool's Alt-click eyedropper, the Curves/Color Picker eyedroppers and the Info panel), `eyedropperSample` (`current`, `currentAndBelow`, `all`, `allNoAdjustments`, `currentAndBelowNoAdjustments`) and `eyedropperRing` (boolean, Show Sampling Ring). `ui.inspect` reports them under `toolOptions` (`eyedropper_size`, `eyedropper_sample`, `eyedropper_ring`). The engine command `document.sampleColor {x, y, size, sampleLayer}` returns the colour such a sample picks, as four floats 0..1 (not 0..255).
diff --git a/docs/ui-parity.md b/docs/ui-parity.md
index 8a189ad491..ff0b3e2111 100644
--- a/docs/ui-parity.md
+++ b/docs/ui-parity.md
@@ -234,7 +234,7 @@ Paragraph; the rest open as in-app floating windows.
 | Themes: Photoshop's four greys | partial | five themes; #2661 |
 | Document tabs: overflow, context menu, reorder | done | UI-217-6; middle-click close #2570 |
 | Layers panel: wheel steps blend modes, drop on New/Trash | partial | UI-217-14 |
-| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name and Mode; the other six missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048) |
+| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name, Mode and Smart Object (linked, missing and embedded; no library links or out-of-date state); the other five missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048) |
 | Adjustment scope: clipping control visible above tall Properties editors in a compact dock | done (2026-10-21) | `panels.rs`, `clipping_indicator_tests.rs`; #5231; stack-wide default retained |
 | Smart filter rows: click selects, drag onto another smart object moves, ⌥-drag copies, drag onto Delete removes; with a row selected, the Delete button and the ⌫/Delete key remove that filter, not the smart object | done | `smart_ui.rs`, `layer.smartFilter.transfer` (#4271), `smart_ui::keys` (#4751) |
 | Layers panel: Clip Thumbnails to Layer Bounds (panel menu, `interface.clipThumbnailsToLayerBounds`) | done (2026-10-12) | `layer_thumb_bounds_tests.rs`; #4281. Thumbnail size and the Panel Options dialog to come |
@@ -299,4 +299,5 @@ Paragraph; the rest open as in-app floating windows.
 | 2026-10-14 | minor | Rounded corners on live triangles, polygons and stars: Properties field and on-canvas widgets (TOOL-214-12) |
 | 2026-10-14 | minor | A colour picked in the Color or Swatches panel or the Color Picker recolours the selected type layers (Type tool) or shape fills (shape, Pen and path selection tools) |
 | 2026-10-15 | minor | Color panel: Photoshop's panel-menu modes, colour ramp and copy commands; the theme no longer picks the panel's layout (UI-217-17 done, #2569, #6000) |
+| 2026-10-24 | minor | Layers panel filter row: Smart Object lists linked, missing or embedded smart objects, drivable by `ui.set {layerFilter: {by: "smartObject", smart}}`; no percentage changed |
 | 2026-10-23 | minor | ⌥ + an adjustment's shortcut (⌥⌘L Levels, ⌥⌘M Curves) opens its dialog at the settings of its last OK, as in Photoshop (#8900); no percentage changed |

From b5210494ef523fb11d28dc1de2fe248a684e095c Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sat, 24 Oct 2026 17:58:41 -0700
Subject: [PATCH 007/109] Layers panel: the filter row lists the artboards that
 hold the selected layers

The filter-type dropdown has an Artboard entry after Mode. With it
picked, the Layers panel lists only the artboards that hold the selected
layers and their contents, as the tree shows them (closed groups stay
closed). With nothing selected, or with a selected layer in no artboard,
the panel is not filtered. The type has no controls of its own.

ui.set {layerFilter: {by: "artboard"}} picks the type. The control
protocol, the ui_set description and the parity table document it.
---
 crates/automation/src/server.rs             |  7 +-
 crates/ui-egui/src/control.rs               | 15 ++++
 crates/ui-egui/src/layer_filter_ui.rs       | 79 ++++++++++++++++++---
 crates/ui-egui/src/layer_filter_ui_tests.rs | 77 +++++++++++++++++++-
 crates/ui-egui/src/panels.rs                |  2 +-
 docs/control-protocol.md                    |  2 +-
 docs/ui-parity.md                           |  3 +-
 7 files changed, 167 insertions(+), 18 deletions(-)

diff --git a/crates/automation/src/server.rs b/crates/automation/src/server.rs
index f5ccef00c7..1eef187f30 100644
--- a/crates/automation/src/server.rs
+++ b/crates/automation/src/server.rs
@@ -346,9 +346,10 @@ pub struct UiSetParams {
     /// dashes, dashOffset and opacity; null disables the stroke). Shape stroke fields use
     /// `shape.edit` names and units; colour comes from `tools.setColors`. camTransformOnDrop (bool,
     /// the Content-Aware Move tool's Transform On Drop). tileGrid (bool, a developer overlay of the
-    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name" or
-    /// "mode"), kinds (a list of layer kinds), name (matches part of the layer name) and mode (a
-    /// blend mode name) for the Layers panel filter). strokeTrace (true, false, "stderr" or "off":
+    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name", "mode"
+    /// or "artboard", which lists the artboards that hold the selected layers), kinds (a list of
+    /// layer kinds), name (matches part of the layer name) and mode (a blend mode name) for the
+    /// Layers panel filter). strokeTrace (true, false, "stderr" or "off":
     /// the stroke latency trace at runtime; a CSV file is set at launch with --stroke-trace, not
     /// over this channel). updatesOpen (bool, the Help › Check for Updates window). Other fields
     /// are an error.
diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs
index b85427c6fa..3fcd24498d 100644
--- a/crates/ui-egui/src/control.rs
+++ b/crates/ui-egui/src/control.rs
@@ -2041,6 +2041,21 @@ mod tests {
         assert!(app.ui.tool_options.gradient_classic, "invalid mode must not change options");
     }
 
+    /// The Layers panel's Artboard filter type is drivable; it has no criteria of its own.
+    #[test]
+    fn ui_set_drives_the_layers_panel_artboard_filter() {
+        use crate::layer_filter_ui::FilterBy;
+        let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+        let ctx = egui::Context::default();
+        let ok = call(&mut app, &ctx, "ui.set", json!({"layerFilter": {"by": "artboard"}}));
+        assert_eq!(ok["ok"], true, "{ok}");
+        assert_eq!(app.ui.layer_filter_by, FilterBy::Artboard);
+        let bad = call(&mut app, &ctx, "ui.set", json!({"layerFilter": {"by": "artboards"}}));
+        assert_eq!(bad["ok"], false, "{bad}");
+        assert!(bad.to_string().contains("kind, name, mode or artboard"), "{bad}");
+        assert_eq!(app.ui.layer_filter_by, FilterBy::Artboard, "a bad value changed nothing");
+    }
+
     /// #5048: the Layers panel filter is drivable; a bad field changes nothing.
     #[test]
     fn ui_set_drives_the_layers_panel_filter() {
diff --git a/crates/ui-egui/src/layer_filter_ui.rs b/crates/ui-egui/src/layer_filter_ui.rs
index e933d0c165..275ecf8753 100644
--- a/crates/ui-egui/src/layer_filter_ui.rs
+++ b/crates/ui-egui/src/layer_filter_ui.rs
@@ -1,10 +1,12 @@
 //! The Layers panel's filter row (#5048): a filter-type dropdown, as in Photoshop, then the
 //! controls for that type. Kind toggles layer kinds, Name matches part of the layer name, Mode
-//! picks one blend mode. The criteria live in `UiState` (`layer_filter*`), so the control channel
-//! can read and set them.
+//! picks one blend mode, Artboard lists only the artboards that hold the selected layers. The
+//! criteria live in `UiState` (`layer_filter*`), so the control channel can read and set them.
+
+use std::collections::HashSet;
 
 use photocraft_color::BlendMode;
-use photocraft_doc::{Layer, LayerContent};
+use photocraft_doc::{Document, Layer, LayerContent, LayerId};
 use serde::{Deserialize, Serialize};
 
 use crate::state::UiState;
@@ -18,6 +20,7 @@ pub enum FilterBy {
     Kind,
     Name,
     Mode,
+    Artboard,
 }
 
 /// The filter criteria, copied out of `UiState` for one frame of the Layers panel.
@@ -28,20 +31,43 @@ pub struct Filter {
     /// As typed; matched trimmed and ignoring case.
     pub name: String,
     pub mode: BlendMode,
+    /// The rows the Artboard filter lists ([`board_rows`]); empty lists every row.
+    pub board_rows: HashSet<LayerId>,
 }
 
 impl Filter {
     pub fn of(ui: &UiState) -> Self {
-        Self { by: ui.layer_filter_by, kinds: ui.layer_filter.clone(), name: ui.layer_filter_name.clone(), mode: ui.layer_filter_mode }
+        Self {
+            by: ui.layer_filter_by,
+            kinds: ui.layer_filter.clone(),
+            name: ui.layer_filter_name.clone(),
+            mode: ui.layer_filter_mode,
+            board_rows: HashSet::new(),
+        }
+    }
+
+    /// Returns [`Filter::of`] for `app`'s settings, with `board_rows` set to the rows of the
+    /// artboards that hold the active document's selected layers while the panel filters by
+    /// Artboard.
+    pub fn of_app(app: &PhotocraftApp) -> Self {
+        let mut f = Self::of(&app.ui);
+        if f.by == FilterBy::Artboard
+            && let Some(d) = app.session.active()
+        {
+            f.board_rows = board_rows(&d.doc, &d.selected_layers());
+        }
+        f
     }
 
     /// Whether the panel is filtered. Like Photoshop, Mode always filters (by Normal at first);
-    /// Kind and Name only once a kind is toggled or some text is typed.
+    /// Kind and Name only once a kind is toggled or some text is typed; Artboard only while some
+    /// layers are selected and each of them is in an artboard.
     pub fn active(&self) -> bool {
         match self.by {
             FilterBy::Kind => !self.kinds.is_empty(),
             FilterBy::Name => !self.name.trim().is_empty(),
             FilterBy::Mode => true,
+            FilterBy::Artboard => !self.board_rows.is_empty(),
         }
     }
 
@@ -54,25 +80,54 @@ impl Filter {
             FilterBy::Kind => self.kinds.iter().any(|k| k == kind(l)),
             FilterBy::Name => l.name.to_lowercase().contains(&self.name.trim().to_lowercase()),
             FilterBy::Mode => l.blend == self.mode,
+            FilterBy::Artboard => self.board_rows.contains(&l.id),
         }
     }
 }
 
+/// The Artboard filter's rows for `selection`: the artboards that hold the selected layers and
+/// every layer inside them. The set is empty when nothing is selected or a selected layer is in
+/// no artboard, and the panel is then not filtered. The panel lists these rows as its tree does: the contents of a closed
+/// group stay hidden until the group is opened (`layer_tree_ui::panel_rows` opens every group only
+/// for the types whose matches can sit in a closed group).
+pub fn board_rows(doc: &Document, selection: &[LayerId]) -> HashSet<LayerId> {
+    fn add(l: &Layer, rows: &mut HashSet<LayerId>) {
+        rows.insert(l.id);
+        for c in l.children().unwrap_or_default() {
+            add(c, rows);
+        }
+    }
+    let mut boards = Vec::new();
+    for &id in selection {
+        let Some(board) = doc.artboard_of(id) else { return HashSet::new() };
+        if !boards.contains(&board) {
+            boards.push(board);
+        }
+    }
+    let mut rows = HashSet::new();
+    for board in boards {
+        if let Some(l) = doc.layer(board) {
+            add(l, &mut rows);
+        }
+    }
+    rows
+}
+
 /// The kinds the Kind filter toggles.
 pub const KINDS: [&str; 5] = ["pixel", "adjustment", "type", "shape", "smart"];
 
 /// `ui.set {layerFilter: {by?, kinds?, name?, mode?}}`: `current` with the given fields replaced,
-/// or an error naming the bad field (nothing changes then). `by` is `kind`, `name` or `mode`;
-/// `kinds` a list of [`KINDS`]; `mode` a blend mode name such as `Multiply` or `Pass Through`.
+/// or an error naming the bad field (nothing changes then). `by` is `kind`, `name`, `mode` or
+/// `artboard`; `kinds` a list of [`KINDS`]; `mode` a blend mode name such as `Multiply` or
+/// `Pass Through`. Artboard has no criteria of its own: the selected layers pick the artboards.
 pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, String> {
     let Some(o) = v.as_object() else { return Err("layerFilter must be an object".into()) };
     if let Some(k) = o.keys().find(|k| !["by", "kinds", "name", "mode"].contains(&k.as_str())) {
         return Err(format!("unknown layerFilter field `{k}` (fields: by, kinds, name, mode)"));
     }
-    let mut f =
-        Filter { by: current.layer_filter_by, kinds: current.layer_filter.clone(), name: current.layer_filter_name.clone(), mode: current.layer_filter_mode };
+    let mut f = Filter::of(current);
     if let Some(by) = o.get("by") {
-        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name or mode".to_string())?;
+        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name, mode or artboard".to_string())?;
     }
     if let Some(kinds) = o.get("kinds") {
         let list = kinds.as_array().ok_or("layerFilter.kinds must be a list")?;
@@ -122,7 +177,7 @@ fn kind(l: &Layer) -> &'static str {
 pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     ui.horizontal(|ui| {
         ui.spacing_mut().item_spacing.x = 2.0;
-        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode"))];
+        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode")), (FilterBy::Artboard, tl!("Artboard"))];
         widgets::dropdown(ui, "layer-filter-by", &mut app.ui.layer_filter_by, &by, 64.0);
         ui.add_space(4.0);
         match app.ui.layer_filter_by {
@@ -153,6 +208,8 @@ pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
                 let width = ui.available_width().max(96.0);
                 widgets::dropdown(ui, "layer-filter-mode", &mut app.ui.layer_filter_mode, &modes, width);
             }
+            // Artboard has no controls: the selected layers pick the artboards ([`board_rows`]).
+            FilterBy::Artboard => {}
         }
     });
 }
diff --git a/crates/ui-egui/src/layer_filter_ui_tests.rs b/crates/ui-egui/src/layer_filter_ui_tests.rs
index aeeb63e7cc..aa7cb6418b 100644
--- a/crates/ui-egui/src/layer_filter_ui_tests.rs
+++ b/crates/ui-egui/src/layer_filter_ui_tests.rs
@@ -1,4 +1,4 @@
-//! #5048: the Layers panel's filter-type dropdown (Kind, Name, Mode).
+//! #5048: the Layers panel's filter-type dropdown (Kind, Name, Mode, Artboard).
 
 use egui::vec2;
 use egui_kittest::Harness;
@@ -135,3 +135,78 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
     h.run_steps(4);
     assert_eq!(drawn(&h), ["ink notes"]);
 }
+
+/// On a Background: the artboard "Back" holding "Grass", the artboard "Front" holding the group
+/// "Trees" with "Oak", and "Loose" in no artboard, on top.
+fn boards_session() -> photocraft_engine::Session {
+    let mut s = photocraft_engine::Session::new();
+    s.execute("file.new", json!({"width": 64, "height": 48})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Grass"})).unwrap();
+    s.execute("layer.new.artboardFromLayers", json!({"name": "Back"})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Oak"})).unwrap();
+    s.execute("layer.groupLayers", json!({"name": "Trees"})).unwrap();
+    s.execute("layer.new.artboardFromLayers", json!({"name": "Front"})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Loose"})).unwrap();
+    s.execute("layer.setExpanded", json!({"all": true, "expanded": true})).unwrap();
+    s
+}
+
+/// The names the Artboard filter lists with the layers `names` selected, every group open.
+fn listed_by_artboard(s: &mut photocraft_engine::Session, names: &[&str]) -> Vec<String> {
+    s.execute("select.deselectLayers", json!({})).unwrap();
+    for (i, name) in names.iter().enumerate() {
+        let id = layer(&s.active().unwrap().doc, name);
+        s.execute("layer.select", json!({"layer": id, "mode": if i == 0 { "replace" } else { "add" }})).unwrap();
+    }
+    let d = s.active().unwrap();
+    let mut f = filter(FilterBy::Artboard, &[], "", BlendMode::Normal);
+    f.board_rows = super::board_rows(&d.doc, &d.selected_layers());
+    listed(&d.doc, &f)
+}
+
+#[test]
+fn the_artboard_filter_lists_the_artboards_that_hold_the_selected_layers() {
+    let mut s = boards_session();
+    let all = ["Loose", "Front", "Trees", "Oak", "Back", "Grass", "Background"];
+    assert_eq!(listed_by_artboard(&mut s, &[]), all, "nothing selected: every layer");
+    // A layer at any depth in an artboard, or the artboard itself: that artboard only.
+    assert_eq!(listed_by_artboard(&mut s, &["Oak"]), ["Front", "Trees", "Oak"]);
+    assert_eq!(listed_by_artboard(&mut s, &["Front"]), ["Front", "Trees", "Oak"]);
+    assert_eq!(listed_by_artboard(&mut s, &["Grass"]), ["Back", "Grass"]);
+    // Layers in two artboards: both artboards.
+    assert_eq!(listed_by_artboard(&mut s, &["Oak", "Grass"]), ["Front", "Trees", "Oak", "Back", "Grass"]);
+    // A selected layer in no artboard: every layer again.
+    assert_eq!(listed_by_artboard(&mut s, &["Loose"]), all);
+    assert_eq!(listed_by_artboard(&mut s, &["Oak", "Loose"]), all);
+    let round = serde_json::to_value(UiState { layer_filter_by: FilterBy::Artboard, ..UiState::default() }).unwrap();
+    assert_eq!(round["layer_filter_by"], "artboard");
+}
+
+#[test]
+fn the_artboard_filter_follows_the_selection_in_the_panel() {
+    let session = boards_session();
+    let mut h = Harness::builder().with_size(vec2(1440.0, 900.0)).with_max_steps(64).build_eframe(move |cc| {
+        PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());
+        PhotocraftApp::new(session, crate::Services::default())
+    });
+    h.run_steps(8);
+    let all = ["Loose", "Front", "Trees", "Oak", "Back", "Grass", "Background"];
+    h.get_by_value("Kind").click();
+    h.run_steps(4);
+    h.query_all_by_label("Artboard").last().expect("Artboard in the open list").click();
+    h.run_steps(4);
+    assert_eq!(h.state().ui.layer_filter_by, FilterBy::Artboard);
+    assert_eq!(drawn(&h), all, "Loose, in no artboard, is selected: every layer");
+    let oak = layer(&h.state().session.active().unwrap().doc, "Oak");
+    h.state_mut().session.execute("layer.select", json!({"layer": oak})).unwrap();
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["Front", "Trees", "Oak"]);
+    // The artboard's tree as the panel shows it: a closed group keeps its contents hidden.
+    let trees = layer(&h.state().session.active().unwrap().doc, "Trees");
+    h.state_mut().session.execute("layer.setExpanded", json!({"layer": trees, "expanded": false})).unwrap();
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["Front", "Trees"]);
+    h.state_mut().session.execute("select.deselectLayers", json!({})).unwrap();
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["Loose", "Front", "Trees", "Back", "Grass", "Background"], "nothing selected: every row");
+}
diff --git a/crates/ui-egui/src/panels.rs b/crates/ui-egui/src/panels.rs
index b6bd34d9d2..f8dc2b563b 100644
--- a/crates/ui-egui/src/panels.rs
+++ b/crates/ui-egui/src/panels.rs
@@ -2714,7 +2714,7 @@ fn layers(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
                 ui.scroll_with_delta(vec2(0.0, delta));
                 ctx.request_repaint();
             }
-            let filter = crate::layer_filter_ui::Filter::of(&app.ui);
+            let filter = crate::layer_filter_ui::Filter::of_app(app);
             let fx_collapsed = app.session.active().map(|d| d.fx_collapsed.clone()).unwrap_or_default();
             crate::layer_row_ui::begin(ui.ctx());
             // The drawn rows, top to bottom (#1721): the space between them and below the last
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 3d4d601b30..6a2e32aa02 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -54,7 +54,7 @@ The transport is `apps/photocraft/src/control_server.rs`, and the handlers are i
 - `ui.set` also accepts `camTransformOnDrop` (boolean), the Content-Aware Move tool's Transform On Drop checkbox: a drop then puts a scale/rotate box on the patch (`ui.inspect` › `camTransform`: its document/revision, drag `offset` and `frame`), driven with `ui.pointer` (handles as Free Transform's; outside the box rotates), committed with `ui.key Enter` (one `paint.contentAwareMove` with `scaleX`, `scaleY`, `rotate`) or dropped with `Escape`.
 - `ui.set` also accepts `tileGrid` (boolean), a developer overlay of the active layer's storage tiles: the tile grid over the document, every stored tile filled and labelled `tx,ty`, tiles with identical pixels in a shared colour and unique ones in blue. It has no menu item and View › Extras doesn't hide it. `ui.inspect` reports it as `view.tile_grid`.
 - `ui.set` also accepts `strokeTrace` (`true`, `false`, `"stderr"` or `"off"`): turn the stroke latency trace on or off at runtime; each stroke's summary is in `ui.inspect` `perf.strokeTrace`. A CSV file of every frame is set only at launch (`PHOTOCRAFT_STROKE_TRACE=<file.csv>` / `--stroke-trace <file.csv>`): the control channel doesn't write files outside the automation write root
-- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?}`, any subset. `by` is `kind`, `name` or `mode` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`). Kind and Name filter only once a kind is on or text is typed; Mode always filters, by Normal at first, as in Photoshop. Fields left out keep their value; a bad one is an error and changes nothing.
+- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?}`, any subset. `by` is `kind`, `name`, `mode` or `artboard` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`). Kind and Name filter only once a kind is on or text is typed; Mode always filters, by Normal at first, as in Photoshop. Artboard has no field of its own: it lists the artboards that hold the selected layers, with everything inside them (closed groups stay closed), and does not filter when nothing is selected or a selected layer is in no artboard. Fields left out keep their value; a bad one is an error and changes nothing.
 - Each painting tool keeps its own brush, as in Photoshop: `tools.setBrush` and `ui.set {brushSize}` change the active tool's brush, and switching tools swaps in that tool's own (size, hardness, mode, opacity, flow, dynamics, smoothing). A tool used for the first time starts from the brush in hand. The colours, the erase flag and the stroke seed stay shared. So `ui.set {tool: "eraser", brushSize: 12}` sets the Eraser's size, and `ui.set {tool: "brush"}` afterwards brings the Brush's own size back.
 - Brush Pose's `pose.overrideTiltX` and `pose.overrideTiltY` are independent booleans. For example, `engine.execute {"command":"tools.setBrush","params":{"pose":{"enabled":true,"tiltX":45,"overrideTiltX":true,"overrideTiltY":false}}}` fixes X at 45° while Y follows the stylus. Pose tilts are degrees (±90); the Brush Settings panel displays percentages (±100). Old stored `overrideTilt` values migrate to both axes. In command patches, `overrideTilt` sets both axes unless an explicit axis field in the same patch overrides it. `brush.get` includes both axis flags and the legacy combined readback (`overrideTilt` is true only when both flags are true). Axis-only journals omit that derived combined key so replay retains the other axis. Present flag values must be booleans; null and other types return an error.
 - `ui.set` also accepts the Eyedropper options bar (#1649): `eyedropperSampleSize` (`"point"` or 1, 3, 5, 11, 31, 51, 101: the side of the averaged square, shared by the Eyedropper, a painting tool's Alt-click eyedropper, the Curves/Color Picker eyedroppers and the Info panel), `eyedropperSample` (`current`, `currentAndBelow`, `all`, `allNoAdjustments`, `currentAndBelowNoAdjustments`) and `eyedropperRing` (boolean, Show Sampling Ring). `ui.inspect` reports them under `toolOptions` (`eyedropper_size`, `eyedropper_sample`, `eyedropper_ring`). The engine command `document.sampleColor {x, y, size, sampleLayer}` returns the colour such a sample picks, as four floats 0..1 (not 0..255).
diff --git a/docs/ui-parity.md b/docs/ui-parity.md
index 8a189ad491..2049d14612 100644
--- a/docs/ui-parity.md
+++ b/docs/ui-parity.md
@@ -234,7 +234,7 @@ Paragraph; the rest open as in-app floating windows.
 | Themes: Photoshop's four greys | partial | five themes; #2661 |
 | Document tabs: overflow, context menu, reorder | done | UI-217-6; middle-click close #2570 |
 | Layers panel: wheel steps blend modes, drop on New/Trash | partial | UI-217-14 |
-| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name and Mode; the other six missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048) |
+| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name, Mode and Artboard; the other five missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048) |
 | Adjustment scope: clipping control visible above tall Properties editors in a compact dock | done (2026-10-21) | `panels.rs`, `clipping_indicator_tests.rs`; #5231; stack-wide default retained |
 | Smart filter rows: click selects, drag onto another smart object moves, ⌥-drag copies, drag onto Delete removes; with a row selected, the Delete button and the ⌫/Delete key remove that filter, not the smart object | done | `smart_ui.rs`, `layer.smartFilter.transfer` (#4271), `smart_ui::keys` (#4751) |
 | Layers panel: Clip Thumbnails to Layer Bounds (panel menu, `interface.clipThumbnailsToLayerBounds`) | done (2026-10-12) | `layer_thumb_bounds_tests.rs`; #4281. Thumbnail size and the Panel Options dialog to come |
@@ -292,6 +292,7 @@ Paragraph; the rest open as in-app floating windows.
 | 2026-10-14 | minor | Move › Show Transform Controls frames every selected layer and outlines the selected shapes |
 | 2026-10-21 | minor | Crop rows corrected against the code and the scorecard: saved custom crop presets (TOOL-214-9, #2723) and Delete Cropped Pixels off are done (#6562); no percentage changed |
 | 2026-10-20 | minor | Free Transform of an artboard child omits ancestor paper from the covering and isolated composites while retaining board clipping. The base canvas and whole-artboard backgrounds are preserved; synthetic regressions in `transform_tool.rs`. No parity percentage changed. |
+| 2026-10-24 | minor | Layers panel filter row: Artboard lists only the artboards that hold the selected layers, and the unfiltered tree when nothing is selected or a selected layer is in no artboard; drivable by `ui.set {layerFilter: {by: "artboard"}}`; no percentage changed |
 | 2026-10-18 | minor | Move tool: dragging selected pixels shrinks the marching ants to the moved pixels as the drag starts, and the dropped selection is theirs, as in Photoshop (#7538) |
 | 2026-10-18 | minor | Marching ants drawn in device pixels like Photoshop's: equally thick on every edge at 125 %/150 % display scale, thicker on HiDPI, slanted dash ends (#7489) |
 | 2026-10-16 | minor | View › Extras (⌘H) hides the Move tool's transform controls and their handles stop responding; ⌘H again restores them, and Show Transform Controls keeps its setting (#6699) |

From a120492156722dee95d33205563d0e0006b4648b Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sat, 24 Oct 2026 18:19:46 -0700
Subject: [PATCH 008/109] Smart objects: closing a document forgets its missing
 files, and updateChanged drops an older look

Session::close now forgets which of the document's linked files were
missing, so a document reopened with the same id lists none until the
next look. layer.smartObjects.updateChanged drops a look still running
on a worker thread, which stamped the files earlier and could clear a
missing file the command had just found.
---
 crates/engine/src/lib.rs        |  1 +
 crates/engine/src/link_watch.rs | 41 +++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 3e79faa0a7..50fa5dec51 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -670,6 +670,7 @@ impl Session {
             self.cancel_jobs_on(id);
             self.subject_cache.forget_doc(id);
             self.object_finder.forget_doc(id);
+            self.link_missing.retain(|(d, _)| *d != id.0);
         }
         let d = self.docs.remove(index);
         self.active = if self.docs.is_empty() {
diff --git a/crates/engine/src/link_watch.rs b/crates/engine/src/link_watch.rs
index acbcfed472..27d04bdce8 100644
--- a/crates/engine/src/link_watch.rs
+++ b/crates/engine/src/link_watch.rs
@@ -68,6 +68,9 @@ pub(crate) fn update_changed(s: &mut Session, _: &Value) -> Result<Value> {
     let st = s.active().ok_or(EngineError::NoDocument)?;
     let (doc, files) = (st.doc.id.0, resolved_files(st));
     let now = files.into_iter().map(|(p, file, ids)| (p, ids, stamp(file.as_deref()))).collect();
+    // Drop a look still running on a worker thread. It stamped the files before this one, and
+    // applying it later would replace this look's result.
+    s.link_scan = None;
     s.apply_link_stamps(doc, now)
 }
 
@@ -330,6 +333,44 @@ mod tests {
         assert!(s.missing_links().is_empty(), "the file is back");
     }
 
+    #[test]
+    fn a_reopened_document_lists_no_file_missing_before_it_closed() {
+        let d = dir("reopen");
+        let (path, saved) = (d.join("art.png"), d.join("doc.pcraft"));
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, _) = placed(&path);
+        s.execute("file.saveACopy", json!({"path": saved.to_string_lossy()})).unwrap();
+        let id = s.active().unwrap().doc.id;
+        std::fs::remove_file(&path).unwrap();
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert_eq!(s.missing_links().len(), 1);
+        s.close(0);
+        std::fs::write(&path, png(10, 10, "#0000ff")).unwrap();
+        let bytes = std::fs::read(&saved).unwrap();
+        crate::file_cmds::open_bytes_as(&mut s, "doc.pcraft", &bytes, None, Some(saved.to_string_lossy().into_owned())).unwrap();
+        assert_eq!(s.active().unwrap().doc.id, id, "the saved document keeps its id");
+        assert!(s.missing_links().is_empty(), "nothing looked at since it opened");
+    }
+
+    #[test]
+    fn a_look_started_before_update_changed_does_not_replace_its_result() {
+        let d = dir("stale");
+        let path = d.join("art.png");
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, _) = placed(&path);
+        s.start_link_scan();
+        let t0 = std::time::Instant::now();
+        while s.link_scan.as_ref().is_some_and(|l| l.lock().unwrap_or_else(std::sync::PoisonError::into_inner).is_none()) {
+            assert!(t0.elapsed().as_secs() < 10, "the look never finished");
+            std::thread::sleep(std::time::Duration::from_millis(5));
+        }
+        std::fs::remove_file(&path).unwrap();
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert_eq!(s.missing_links().len(), 1);
+        let _ = s.poll_link_scan();
+        assert_eq!(s.missing_links().len(), 1, "the earlier look found the file, but it is gone");
+    }
+
     #[test]
     fn a_background_look_updates_changed_files() {
         let d = dir("scan");

From c11b25db46864375a250637d0b2db3eca3d2a435 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sun, 25 Oct 2026 17:26:49 -0700
Subject: [PATCH 009/109] Layers panel: the Artboard filter walks each
 artboard's layers once

board_rows looked up each selected layer's artboard with a search from the document root. It now walks every top-level artboard once and keeps the artboards that hold a selected layer. The filter still clears when a selected layer is in no artboard.
---
 crates/ui-egui/src/layer_filter_ui.rs | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/crates/ui-egui/src/layer_filter_ui.rs b/crates/ui-egui/src/layer_filter_ui.rs
index 275ecf8753..583d526928 100644
--- a/crates/ui-egui/src/layer_filter_ui.rs
+++ b/crates/ui-egui/src/layer_filter_ui.rs
@@ -97,18 +97,23 @@ pub fn board_rows(doc: &Document, selection: &[LayerId]) -> HashSet<LayerId> {
             add(c, rows);
         }
     }
-    let mut boards = Vec::new();
-    for &id in selection {
-        let Some(board) = doc.artboard_of(id) else { return HashSet::new() };
-        if !boards.contains(&board) {
-            boards.push(board);
+    let selected: HashSet<LayerId> = selection.iter().copied().collect();
+    if selected.is_empty() {
+        return HashSet::new();
+    }
+    // Artboards are top-level groups ([`Document::artboard_of`]): each one's layers are walked once.
+    let (mut rows, mut held) = (HashSet::new(), 0);
+    for board in doc.layers.iter().filter(|l| l.artboard().is_some()) {
+        let mut inside = HashSet::new();
+        add(board, &mut inside);
+        let n = selected.iter().filter(|id| inside.contains(id)).count();
+        if n > 0 {
+            held += n;
+            rows.extend(inside);
         }
     }
-    let mut rows = HashSet::new();
-    for board in boards {
-        if let Some(l) = doc.layer(board) {
-            add(l, &mut rows);
-        }
+    if held < selected.len() {
+        return HashSet::new();
     }
     rows
 }

From 8073571ad9b705342738d2c05e1e75c9c33f95dc Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Mon, 26 Oct 2026 22:58:30 -0700
Subject: [PATCH 010/109] Clean up Smart Object filter test fixtures

Keep the temporary directory handle alive in both fixture users so each
directory is removed when its test finishes.
---
 .../ui-egui/src/panels/layer_filter_ui/tests.rs  | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index 5f30052010..e07936a6a8 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -136,16 +136,14 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
     assert_eq!(drawn(&h), ["ink notes"]);
 }
 
-/// A PNG at `<temp>/<name>/art.png` (a folder per test: tests run in parallel).
-fn art_file(name: &str) -> std::path::PathBuf {
-    let d = std::env::temp_dir().join(format!("photocraft-layer-filter-{name}-{}", std::process::id()));
-    let _ = std::fs::remove_dir_all(&d);
-    std::fs::create_dir_all(&d).unwrap();
-    let file = d.join("art.png");
+/// Creates a PNG fixture and returns its temporary directory with the file path.
+fn art_file() -> (tempfile::TempDir, std::path::PathBuf) {
+    let directory = tempfile::tempdir().unwrap();
+    let file = directory.path().join("art.png");
     let mut s = photocraft_engine::Session::new();
     s.execute("file.new", json!({"width": 8, "height": 8, "background": "#ff0000"})).unwrap();
     s.execute("file.saveACopy", json!({"path": file.to_string_lossy(), "layers": false})).unwrap();
-    file
+    (directory, file)
 }
 
 /// "Linked art" (linked to `file`) above "Embedded art" (a copy of `file`), "Plain" and
@@ -168,7 +166,7 @@ fn by_smart(smart: &[&str], missing: std::collections::HashSet<String>) -> Filte
 
 #[test]
 fn the_smart_object_filter_lists_linked_missing_and_embedded_smart_objects() {
-    let file = art_file("list");
+    let (_directory, file) = art_file();
     let mut s = smart_session(&file);
     let doc = &s.active().unwrap().doc;
     let none = std::collections::HashSet::new;
@@ -202,7 +200,7 @@ fn saved_settings_without_the_smart_object_toggles_still_load() {
 
 #[test]
 fn the_smart_object_toggles_filter_the_panel() {
-    let file = art_file("panel");
+    let (_directory, file) = art_file();
     let session = smart_session(&file);
     let mut h = Harness::builder().with_size(vec2(1440.0, 900.0)).with_max_steps(64).build_eframe(move |cc| {
         PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());

From 92b4e9b9de264d1f002edf3079b3a97dd2b60e07 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Tue, 27 Oct 2026 00:11:47 -0700
Subject: [PATCH 011/109] Cancel pending link scans when closing a document

Discard background scan results when a document closes so they cannot change the missing-link state after the same document reopens.
---
 crates/engine/src/link_watch.rs        | 21 +++++++++++++++++++++
 crates/engine/src/session/documents.rs |  1 +
 2 files changed, 22 insertions(+)

diff --git a/crates/engine/src/link_watch.rs b/crates/engine/src/link_watch.rs
index 27d04bdce8..21f7007302 100644
--- a/crates/engine/src/link_watch.rs
+++ b/crates/engine/src/link_watch.rs
@@ -371,6 +371,27 @@ mod tests {
         assert_eq!(s.missing_links().len(), 1, "the earlier look found the file, but it is gone");
     }
 
+    #[test]
+    fn a_scan_finished_after_close_cannot_change_a_reopened_document() {
+        let directory = tempfile::tempdir().unwrap();
+        let path = directory.path().join("art.png");
+        let saved = directory.path().join("doc.pcraft");
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, layer) = placed(&path);
+        s.execute("file.saveACopy", json!({"path": saved.to_string_lossy()})).unwrap();
+        let id = s.active().unwrap().doc.id;
+        let stored = super::linked_files(&s.active().unwrap().doc)[0].0.clone();
+        let scan = std::sync::Arc::new(std::sync::Mutex::new(None));
+        s.link_scan = Some(scan.clone());
+        s.close(0);
+        let bytes = std::fs::read(&saved).unwrap();
+        crate::file_cmds::open_bytes_as(&mut s, "doc.pcraft", &bytes, None, Some(saved.to_string_lossy().into_owned())).unwrap();
+        assert_eq!(s.active().unwrap().doc.id, id);
+        *scan.lock().unwrap() = Some((id.0, vec![(stored, vec![layer], None)]));
+        assert!(s.poll_link_scan().is_none());
+        assert!(s.missing_links().is_empty());
+    }
+
     #[test]
     fn a_background_look_updates_changed_files() {
         let d = dir("scan");
diff --git a/crates/engine/src/session/documents.rs b/crates/engine/src/session/documents.rs
index 0bed0c1d1b..3ae9685e12 100644
--- a/crates/engine/src/session/documents.rs
+++ b/crates/engine/src/session/documents.rs
@@ -141,6 +141,7 @@ impl Session {
             self.subject_cache.forget_doc(id);
             self.object_finder.forget_doc(id);
             self.link_missing.retain(|(d, _)| *d != id.0);
+            self.link_scan = None;
         }
         let d = self.docs.remove(index);
         self.active = if self.docs.is_empty() {

From 08c2d0ff06fdc4cc5db0b5cba2fd0c022d31cda9 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Wed, 28 Oct 2026 14:53:16 -0700
Subject: [PATCH 012/109] Layers: build the Artboard filter test document with
 main's layer placement

A new layer now goes into the artboard it is on, and Artboard from Layers
refuses a selection already in an artboard, so the fixture makes every layer
first and forms the artboards from selections. The test groups also set
frame_stroke.
---
 .../src/panels/layer_filter_ui/tests.rs       | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index c61427ab77..3e8be2f1a9 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -142,12 +142,20 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
 fn boards_session() -> photocraft_engine::Session {
     let mut s = photocraft_engine::Session::new();
     s.execute("file.new", json!({"width": 64, "height": 48})).unwrap();
-    s.execute("layer.new.layer", json!({"name": "Grass"})).unwrap();
+    // Every layer is made before the artboards, since a new layer goes into the artboard it is on.
+    for name in ["Grass", "Oak", "Loose"] {
+        s.execute("layer.new.layer", json!({"name": name})).unwrap();
+    }
+    let grass = layer(&s.active().unwrap().doc, "Grass");
+    s.execute("layer.select", json!({"layer": grass})).unwrap();
     s.execute("layer.new.artboardFromLayers", json!({"name": "Back"})).unwrap();
-    s.execute("layer.new.layer", json!({"name": "Oak"})).unwrap();
+    let oak = layer(&s.active().unwrap().doc, "Oak");
+    s.execute("layer.select", json!({"layer": oak})).unwrap();
     s.execute("layer.groupLayers", json!({"name": "Trees"})).unwrap();
     s.execute("layer.new.artboardFromLayers", json!({"name": "Front"})).unwrap();
-    s.execute("layer.new.layer", json!({"name": "Loose"})).unwrap();
+    let loose = layer(&s.active().unwrap().doc, "Loose");
+    s.execute("layer.select", json!({"layer": loose})).unwrap();
+    s.execute("layer.arrange.bringToFront", json!({})).unwrap();
     s.execute("layer.setExpanded", json!({"all": true, "expanded": true})).unwrap();
     s
 }
@@ -219,16 +227,18 @@ fn the_artboard_filter_walks_deep_groups_without_recursion() {
     use photocraft_geom::Rect;
     use std::collections::HashSet;
 
-    let mut nested = Layer::new("Leaf", LayerContent::Group(Group { children: vec![], expanded: false, artboard: None }));
+    let mut nested = Layer::new("Leaf", LayerContent::Group(Group { children: vec![], expanded: false, artboard: None, frame_stroke: None }));
     let selected = nested.id;
     let mut expected = HashSet::from([selected]);
     for _ in 0..16_384 {
-        nested = Layer::new("Group", LayerContent::Group(Group { children: vec![nested], expanded: false, artboard: None }));
+        nested = Layer::new("Group", LayerContent::Group(Group { children: vec![nested], expanded: false, artboard: None, frame_stroke: None }));
         expected.insert(nested.id);
     }
     let mut doc = Document::new("Deep groups", Size::new(8, 8), ColorMode::Rgb, SampleType::U8);
-    let board =
-        Layer::new("Board", LayerContent::Group(Group { children: vec![nested], expanded: true, artboard: Some(Artboard::new(Rect::new(0, 0, 8, 8))) }));
+    let board = Layer::new(
+        "Board",
+        LayerContent::Group(Group { children: vec![nested], expanded: true, artboard: Some(Artboard::new(Rect::new(0, 0, 8, 8))), frame_stroke: None }),
+    );
     expected.insert(board.id);
     doc.layers.push(board);
     std::thread::Builder::new()

From b800c40cfdf115ac831f2f4db5c291fa12e2e4e2 Mon Sep 17 00:00:00 2001
From: RickiNano <81099017+RickiNano@users.noreply.github.com>
Date: Sun, 1 Nov 2026 19:17:45 +0100
Subject: [PATCH 013/109] Don't auto-select off-canvas layers from the
 pasteboard (#10665)

A Move-tool click on the pasteboard with Auto-Select only cleared the layer
selection (#4991) when nothing was hit there, but `layers_hit` was not clipped
to the canvas: fill layers and pixels hanging past the edge were hit on the
pasteboard, so the click selected a layer that isn't drawn there instead.

Outside the canvas of a document without artboards, nothing is hit now, and
the layer marquee is clipped to the canvas the same way. Artboard documents
keep picking over the pasteboard, where they draw their layers (#5712).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/pick_cmds.rs   | 36 ++++++++++++++++++++++++++--
 crates/ui-egui/src/tools/move_box.rs | 25 +++++++++++++++++++
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/pick_cmds.rs b/crates/engine/src/cmd/pick_cmds.rs
index c40e15e9b8..76a9e8b773 100644
--- a/crates/engine/src/cmd/pick_cmds.rs
+++ b/crates/engine/src/cmd/pick_cmds.rs
@@ -26,6 +26,12 @@ fn layers_hit(doc: &Document, x: i32, y: i32, type_bounds: bool) -> Vec<LayerId>
     if x.checked_add(1).is_none() || y.checked_add(1).is_none() {
         return Vec::new();
     }
+    // Off the canvas nothing is drawn (only artboard documents show layers over the pasteboard,
+    // #5712), so pixels hanging past the edge and fill layers can't be hit there: a pasteboard
+    // click with Auto-Select clears the layer selection instead of picking them (#10665).
+    if !doc.has_artboards() && !doc.bounds().contains(x, y) {
+        return Vec::new();
+    }
     let rows = doc.walk();
     let mut out = Vec::new();
     for (path, _, l) in rows.iter().rev() {
@@ -114,13 +120,15 @@ fn pick(s: &mut Session, p: &Value) -> Result<Value> {
 
 /// Layers whose content touches document rect `r`, top to bottom: visible, not fully locked, not
 /// the locked Background (as Select › All Layers). A layer on an artboard counts only where the
-/// board shows it. With `group`, each counts as its outermost group (deduplicated).
+/// board shows it, and without artboards only where the canvas does (#10665). With `group`, each
+/// counts as its outermost group (deduplicated).
 pub fn layers_in_rect(doc: &Document, r: Rect, group: bool) -> Vec<LayerId> {
     let mut out = Vec::new();
+    let canvas = doc.bounds();
+    let r = if doc.has_artboards() { r } else { r.intersect(&canvas) };
     if r.is_empty() {
         return out;
     }
-    let canvas = doc.bounds();
     for (path, _, l) in doc.walk().iter().rev() {
         if matches!(l.content, LayerContent::Group(_) | LayerContent::Adjustment(_))
             || doc.is_background(l.id)
@@ -447,6 +455,30 @@ mod tests {
         assert!(empty.execute("layer.pickAt", json!({"x": 1, "y": 1})).is_err());
     }
 
+    /// #10665: off the canvas nothing is drawn, so a fill layer or pixels hanging past the edge
+    /// are neither picked there nor caught by a marquee that touches only the pasteboard.
+    #[test]
+    fn nothing_is_hit_off_the_canvas() {
+        let mut s = Session::new();
+        s.execute("file.new", json!({"width": 40, "height": 40, "background": "transparent"})).unwrap();
+        let fill = s.execute("layer.newFillLayer.solidColor", json!({"color": "#00ff00"})).unwrap()["layer"].as_u64().unwrap();
+        s.execute("layer.new.layer", json!({"name": "Off"})).unwrap();
+        let off = s.active().unwrap().active_layer.unwrap();
+        s.edit("paint past the edge", |doc, _| {
+            doc.layer_mut(off).unwrap().surface_mut().unwrap().fill_rect(Rect::new(-20, 0, 10, 40), &[1.0, 0.0, 0.0, 1.0]);
+            Ok(())
+        })
+        .unwrap();
+        let pick = |s: &mut Session, x: i32, y: i32| s.execute("layer.pickAt", json!({"x": x, "y": y, "select": false})).unwrap()["layer"].clone();
+        assert_eq!(pick(&mut s, 5, 5), off.0, "on the canvas");
+        assert_eq!(pick(&mut s, 20, 5), fill, "the fill layer covers the canvas");
+        assert_eq!(pick(&mut s, -10, 5), Value::Null, "the pasteboard, over Off's hidden pixels and the fill");
+        assert_eq!(s.execute("layer.pickAt", json!({"x": -10, "y": 5, "list": true})).unwrap()["layers"], json!([]));
+        let in_rect = |s: &mut Session, x: f64| s.execute("layer.selectInRect", json!({"x": x, "y": 0, "width": 5, "height": 5})).unwrap()["layers"].clone();
+        assert_eq!(in_rect(&mut s, -15.0), json!([]), "a marquee on the pasteboard only");
+        assert_eq!(in_rect(&mut s, -3.0), json!([off.0, fill]), "a marquee reaching onto the canvas");
+    }
+
     /// A hide-all mask at density 0 hides nothing (the compositor applies density through
     /// `LayerMask::value`), so the layer stays pickable; at full density it is clicked through.
     #[test]
diff --git a/crates/ui-egui/src/tools/move_box.rs b/crates/ui-egui/src/tools/move_box.rs
index f49a5061be..05f12222b4 100644
--- a/crates/ui-egui/src/tools/move_box.rs
+++ b/crates/ui-egui/src/tools/move_box.rs
@@ -154,6 +154,31 @@ mod tests {
         assert!(app.layer_box.is_none());
     }
 
+    /// #10665: a fill layer, or pixels hanging past the canvas edge, aren't drawn on the
+    /// pasteboard, so a click there still clears the layer selection rather than picking them.
+    #[test]
+    fn pasteboard_click_deselects_over_fill_layers_and_off_canvas_pixels() {
+        let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+        app.run("file.new", json!({"width": 64, "height": 64, "background": "transparent"})).unwrap();
+        app.run("layer.newFillLayer.solidColor", json!({"color": "#00ff00"})).unwrap();
+        app.run("layer.new.layer", json!({})).unwrap();
+        let off = app.session.active().unwrap().active_layer.unwrap();
+        app.session
+            .edit("paint past the edge", |doc, _| {
+                doc.layer_mut(off).unwrap().surface_mut().unwrap().fill_rect(photocraft_geom::Rect::new(-20, 0, 10, 64), &[1.0, 0.0, 0.0, 1.0]);
+                Ok(())
+            })
+            .unwrap();
+        app.run("layer.new.layer", json!({})).unwrap();
+        app.ui.tool = Tool::Move;
+        app.ui.tool_options.move_auto_select = true;
+        tool_event(&mut app, ToolEvent::Down { x: -10.0, y: 30.0, pressure: 1.0 }, egui::Modifiers::NONE);
+        tool_event(&mut app, ToolEvent::Up { x: -10.0, y: 30.0 }, egui::Modifiers::NONE);
+        let st = app.session.active().unwrap();
+        assert!(st.selected_layers().is_empty() && st.active_layer.is_none(), "selected {:?}", st.selected_layers());
+        assert_eq!(st.doc.layer(off).unwrap().surface().unwrap().content_bounds().x0, -20, "nothing moved");
+    }
+
     /// #4058: a drag that starts on the locked Background draws the layer marquee. It does not
     /// open the move-lock dialog, and releasing selects the unlocked layer the box touches.
     #[test]

From 5881923406a06181351d07fa6a3e9de1783622e1 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 12:49:47 -0800
Subject: [PATCH 014/109] fix(engine): replay recorded link and unlink
 explicitly

---
 crates/engine/src/cmd/atn_cmds/events.rs      |  26 ++-
 crates/engine/src/cmd/atn_cmds/tests.rs       |   2 +
 crates/engine/src/cmd/layer_multi_cmds.rs     |  12 +-
 .../src/cmd/layer_multi_cmds/structure.rs     |  23 ++-
 crates/engine/src/session/execute.rs          |   6 +
 crates/engine/tests/it/atn_newer_events.rs    | 182 ++++++++++++++++++
 crates/engine/tests/it/main.rs                |   1 +
 docs/atn.md                                   |  17 ++
 8 files changed, 260 insertions(+), 9 deletions(-)
 create mode 100644 crates/engine/tests/it/atn_newer_events.rs
 create mode 100644 docs/atn.md

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 5723c93c59..67e1aeae75 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -1,6 +1,6 @@
 const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly"), ("LghO", "lightenOnly"), ("Anst", "anisotropic")];
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
-use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, ref_class};
+use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, ref_class, target_ref};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
@@ -175,6 +175,21 @@ fn clipping_to(_: &str, p: &Value) -> Option<Descriptor> {
     Some(desc("null").with("null", layer_ref(p)?))
 }
 
+// Target matching follows #10628's Link Layers adapter. Recorded Link and Unlink
+// need explicit state: replaying the UI toggle can perform the opposite operation.
+fn link_from(d: &Descriptor, linked: bool) -> Mapped {
+    if *d == desc("null").with("null", target_ref("Lyr ")) {
+        step("layer.linkLayers", json!({"linked": linked}))
+    } else {
+        Mapped::Unsupported { harmless: false }
+    }
+}
+
+fn link_to(p: &Value, linked: bool) -> Option<Descriptor> {
+    let p = p.as_object()?;
+    (p.len() == 1 && p.get("linked") == Some(&Value::Bool(linked))).then(|| desc("null").with("null", target_ref("Lyr ")))
+}
+
 /// A clipping mask event: `clipping_from` / `clipping_to` with one command id.
 macro_rules! clipping_event {
     ($code:literal, $name:literal, $label:literal, $id:literal) => {
@@ -353,6 +368,15 @@ pub(super) const EVENTS: &[Event] = &[
     },
     Event { code: "Dplc", name: "duplicate", label: "Duplicate", ids: &["layer.duplicate", "image.duplicate"], from: duplicate_from, to: duplicate_to },
     // Layers.
+    Event { code: "", name: "linkSelectedLayers", label: "Link Layers", ids: &["layer.linkLayers"], from: |d| link_from(d, true), to: |_, p| link_to(p, true) },
+    Event {
+        code: "",
+        name: "unlinkSelectedLayers",
+        label: "Unlink Layers",
+        ids: &["layer.linkLayers"],
+        from: |d| link_from(d, false),
+        to: |_, p| link_to(p, false),
+    },
     Event {
         code: "Mk  ",
         name: "make",
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index f9e633244c..8680429482 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -548,6 +548,8 @@ fn every_mapped_command_exports_and_imports_back() {
         ("layer.new.layer", json!({"name": "Ink", "opacity": 0.5, "mode": "Multiply"})),
         ("layer.new.group", json!({"name": "G"})),
         ("layer.groupLayers", json!({})),
+        ("layer.linkLayers", json!({"linked": true})),
+        ("layer.linkLayers", json!({"linked": false})),
         ("layer.new.layerViaCopy", json!({})),
         ("layer.newFillLayer.solidColor", json!({"color": "#336699"})),
         ("layer.newAdjustmentLayer.hueSaturation", json!({})),
diff --git a/crates/engine/src/cmd/layer_multi_cmds.rs b/crates/engine/src/cmd/layer_multi_cmds.rs
index 79abb250a3..ada040e8b7 100644
--- a/crates/engine/src/cmd/layer_multi_cmds.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds.rs
@@ -134,9 +134,15 @@ pub fn specs() -> Vec<CommandSpec> {
             s,
             "vertically"
         )),
-        spec!("layer.linkLayers", "Link Layers", &["Layer"], None, "{} (toggles: unlinks when the selection is already one link group)", can_link, |s, _| {
-            link_layers(s)
-        }),
+        spec!(
+            "layer.linkLayers",
+            "Link Layers",
+            &["Layer"],
+            None,
+            r#"{"linked":bool?} (omitted: toggle; explicit true links, false unlinks)"#,
+            can_link,
+            link_layers
+        ),
         spec!("layer.mergeLayers", "Merge Layers", &["Layer"], Some("Cmd+E"), "{} (one layer selected: Merge Down)", has_layer, |s, _| merge_layers(s)),
         spec!(
             "layer.new.groupFromLayers",
diff --git a/crates/engine/src/cmd/layer_multi_cmds/structure.rs b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
index 70aa512223..c52f7a3a1d 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/structure.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
@@ -3,13 +3,26 @@ use super::{Document, EngineError, Layer, LayerContent, LayerId, PixelFormat, Re
 
 // ---------- structural commands ----------
 
-pub(super) fn link_layers(s: &mut Session) -> Result<Value> {
+pub(super) fn link_layers(s: &mut Session, p: &Value) -> Result<Value> {
+    let requested = match p.get("linked") {
+        None => None,
+        Some(Value::Bool(value)) => Some(*value),
+        Some(_) => return Err(bad("layer.linkLayers", "`linked` must be true or false")),
+    };
     let sel = selected(s);
-    let linked = s.edit("Link Layers", |doc, _| {
-        let groups: Vec<Option<u64>> = sel.iter().map(|id| doc.layer(*id).and_then(|l| l.link_group)).collect();
+    let doc = &s.active().ok_or(EngineError::NoDocument)?.doc;
+    let groups = sel.iter().map(|id| doc.layer(*id).map(|l| l.link_group).ok_or(EngineError::NoLayer(*id))).collect::<Result<Vec<_>>>()?;
+    let first = groups.first().copied().flatten();
+    let same_group = first.is_some() && groups.iter().all(|group| *group == first);
+    // A recorded Link/Unlink is an operation, not the UI's state-dependent toggle.
+    // An explicit repeat must neither allocate a group nor add an undo entry.
+    if requested == Some(true) && same_group || requested == Some(false) && groups.iter().all(Option::is_none) {
+        return Ok(json!({"linked": requested == Some(true)}));
+    }
+    let label = if requested == Some(false) { "Unlink Layers" } else { "Link Layers" };
+    let linked = s.edit(label, |doc, _| {
         // Already one link group (or a single linked layer): unlink, like Photoshop's toggle.
-        let first = groups.first().copied().flatten();
-        let unlink = first.is_some() && groups.iter().all(|g| *g == first);
+        let unlink = requested.map_or(same_group, |linked| !linked);
         // A loaded file can store any id up to u64::MAX, so the new id must not be a bare
         // max + 1 (#961). Unlinking needs no new id at all.
         let next = if unlink { None } else { Some(doc.unused_link_group().ok_or_else(|| bad("layer.linkLayers", "no free link group id is left"))?) };
diff --git a/crates/engine/src/session/execute.rs b/crates/engine/src/session/execute.rs
index 2c7ef1ba1c..32eb2c6197 100644
--- a/crates/engine/src/session/execute.rs
+++ b/crates/engine/src/session/execute.rs
@@ -150,6 +150,12 @@ impl Session {
         if spec.id == "layer.smartFilter.deleteFilterMask" && params.get("ifPresent").and_then(Value::as_bool) == Some(true) {
             return smart_cmds::smart_layer_active(self);
         }
+        // Recorded Unlink can be repeated on a single, already-unlinked layer.
+        // Keep the menu toggle's two-layer requirement when no state is supplied.
+        if spec.id == "layer.linkLayers" && params.get("linked").and_then(Value::as_bool) == Some(false) {
+            let d = self.active().ok_or_else(|| "no document open".to_string())?;
+            return if d.selected_layers().is_empty() { Err("no layer selected".into()) } else { Ok(()) };
+        }
         channel_cmds::mask_target_enabled(self, spec.id, params).unwrap_or_else(|| (spec.enabled)(self))
     }
 
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
new file mode 100644
index 0000000000..5b56235657
--- /dev/null
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -0,0 +1,182 @@
+//! #10700: recorded Link and Unlink must not replay as a state-dependent toggle.
+use photocraft_doc::{Layer, LayerId};
+use photocraft_engine::{Session, actions_cmds::Action, atn_cmds};
+use photocraft_psd::{
+    atn::{self, AtnAction, AtnEvent, AtnFile, AtnItem},
+    descriptor::{Class, Descriptor, Id, ReferenceItem, UnicodeString, Value as D},
+};
+use serde_json::json;
+use std::sync::Arc;
+
+fn fixture(groups: &[Option<u64>], selected: &[usize]) -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 2, "height": 2})).unwrap();
+    let st = s.active_mut().unwrap();
+    let doc = Arc::make_mut(&mut st.doc);
+    doc.layers = groups
+        .iter()
+        .enumerate()
+        .map(|(i, group)| {
+            let mut layer = Layer::raster(format!("Layer {i}"), doc.pixel_format());
+            layer.link_group = *group;
+            layer
+        })
+        .collect();
+    let ids: Vec<_> = selected.iter().map(|i| doc.layers[*i].id).collect();
+    s.restore_layer_selection(ids.last().copied(), &ids, ids.first().copied()).unwrap();
+    s
+}
+
+fn groups(s: &Session) -> Vec<Option<u64>> {
+    s.active().unwrap().doc.layers.iter().map(|layer| layer.link_group).collect()
+}
+
+fn target() -> D {
+    D::Reference(vec![ReferenceItem::Enumerated {
+        class: Class { name: UnicodeString::new_nul(""), class_id: Id::new("Lyr ") },
+        type_id: Id::new("Ordn"),
+        value: Id::new("Trgt"),
+    }])
+}
+
+fn file(event: &str, descriptor: Descriptor) -> Vec<u8> {
+    atn::write(&AtnFile {
+        name: UnicodeString::new_nul("Links"),
+        expanded: false,
+        actions: vec![AtnAction {
+            name: UnicodeString::new_nul("A"),
+            items: vec![AtnItem { event: AtnEvent::name(event), descriptor: Some(descriptor), ..Default::default() }],
+            ..Default::default()
+        }],
+        warnings: vec![],
+    })
+    .unwrap()
+}
+
+fn load(s: &mut Session, bytes: &[u8]) -> serde_json::Value {
+    s.execute("actions.load", json!({"data": photocraft_engine::paint::tile::b64_encode(bytes)})).unwrap()
+}
+
+#[test]
+fn explicit_links_are_idempotent_and_omitted_state_still_toggles() {
+    let mut s = fixture(&[None, None], &[0, 1]);
+    let before = s.active().unwrap().doc.clone();
+    let history = s.active().unwrap().history.past_len();
+    s.execute("layer.linkLayers", json!({"linked": false})).unwrap();
+    assert_eq!(s.active().unwrap().doc, before);
+    assert_eq!(s.active().unwrap().history.past_len(), history);
+    s.execute("layer.linkLayers", json!({"linked": true})).unwrap();
+    let linked = s.active().unwrap().doc.clone();
+    assert!(groups(&s)[0].is_some());
+    assert_eq!(groups(&s)[0], groups(&s)[1]);
+    let history = s.active().unwrap().history.past_len();
+    s.execute("layer.linkLayers", json!({"linked": true})).unwrap();
+    assert_eq!(s.active().unwrap().doc, linked);
+    assert_eq!(s.active().unwrap().history.past_len(), history);
+    s.execute("layer.linkLayers", json!({})).unwrap();
+    assert_eq!(groups(&s), [None, None]);
+    s.execute("layer.linkLayers", json!({})).unwrap();
+    assert!(groups(&s).iter().all(Option::is_some));
+}
+
+#[test]
+fn unlink_cleans_singletons_preserves_other_groups_and_undoes() {
+    for initial in [vec![Some(77), Some(77), Some(77), Some(93), Some(93)], vec![Some(77), None, Some(77), Some(93), Some(93)]] {
+        let mut s = fixture(&initial, &[0, 1]);
+        let before = s.active().unwrap().doc.clone();
+        s.execute("layer.linkLayers", json!({"linked": false})).unwrap();
+        assert_eq!(groups(&s), [None, None, None, Some(93), Some(93)]);
+        let history = s.active().unwrap().history.past_len();
+        s.execute("layer.linkLayers", json!({"linked": false})).unwrap();
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+    let mut one = fixture(&[Some(77), Some(77)], &[0]);
+    one.execute("layer.linkLayers", json!({"linked": false})).unwrap();
+    assert_eq!(groups(&one), [None, None]);
+    let history = one.active().unwrap().history.past_len();
+    one.execute("layer.linkLayers", json!({"linked": false})).unwrap();
+    assert_eq!(one.active().unwrap().history.past_len(), history);
+    assert!(!one.is_enabled("layer.linkLayers"), "the UI toggle still requires two unlinked layers");
+}
+
+#[test]
+fn invalid_link_state_fails_without_editing() {
+    let mut s = fixture(&[None, None], &[0, 1]);
+    let before = s.active().unwrap().doc.clone();
+    let history = s.active().unwrap().history.past_len();
+    for invalid in [json!(null), json!("false"), json!(0), json!([]), json!({})] {
+        assert!(s.execute("layer.linkLayers", json!({"linked": invalid})).is_err());
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+    for active in [None, Some(LayerId(u64::MAX))] {
+        let st = s.active_mut().unwrap();
+        st.active_layer = active;
+        st.selected_layers = active.into_iter().collect();
+        assert!(s.execute("layer.linkLayers", json!({"linked": false})).is_err());
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+    assert!(Session::new().execute("layer.linkLayers", json!({"linked": false})).is_err());
+}
+
+#[test]
+fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
+    for (event, linked) in [("linkSelectedLayers", true), ("unlinkSelectedLayers", false)] {
+        for initial in [vec![None, None, None, Some(93), Some(93)], vec![Some(77), Some(77), Some(77), Some(93), Some(93)]] {
+            let descriptor = Descriptor::new("null").with("null", target());
+            let mut s = fixture(&initial, &[0, 1]);
+            assert_eq!(load(&mut s, &file(event, descriptor.clone()))["unsupported"], json!([]));
+            assert_eq!(s.actions.list[0].steps, [("layer.linkLayers".into(), json!({"linked": linked}))]);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            assert_eq!(saved["skipped"], json!([]));
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            let parsed = atn::parse(&bytes).unwrap();
+            assert_eq!(parsed.actions[0].items[0].event, AtnEvent::name(event));
+            assert_eq!(parsed.actions[0].items[0].descriptor, Some(descriptor));
+            let mut replay = fixture(&initial, &[0, 1]);
+            assert_eq!(load(&mut replay, &bytes)["unsupported"], json!([]));
+            replay.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+            if linked {
+                let result = groups(&replay);
+                assert!(result[0].is_some());
+                assert_eq!(result[0], result[1]);
+                assert_eq!(&result[2..], &[initial[2], Some(93), Some(93)]);
+            } else {
+                assert_eq!(groups(&replay), [None, None, None, Some(93), Some(93)]);
+            }
+            let before = replay.active().unwrap().doc.clone();
+            let history = replay.active().unwrap().history.past_len();
+            replay.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+            assert_eq!(replay.active().unwrap().doc, before);
+            assert_eq!(replay.active().unwrap().history.past_len(), history);
+        }
+    }
+}
+
+#[test]
+fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
+    for event in ["linkSelectedLayers", "unlinkSelectedLayers"] {
+        for descriptor in [
+            Descriptor::new("null"),
+            Descriptor::new("null").with("null", D::Integer(1)),
+            Descriptor::new("other").with("null", target()),
+            Descriptor::new("null").with("null", target()).with("extra", D::Boolean(true)),
+            Descriptor::new("null").with("null", target()).with("null", target()),
+        ] {
+            let mut s = Session::new();
+            assert_eq!(load(&mut s, &file(event, descriptor.clone()))["unsupported"].as_array().unwrap().len(), 1);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            let parsed = atn::parse(&bytes).unwrap();
+            assert_eq!(parsed.actions[0].items[0].event, AtnEvent::name(event));
+            assert_eq!(parsed.actions[0].items[0].descriptor, Some(descriptor));
+        }
+    }
+    for params in [json!({}), json!({"linked": null}), json!({"linked": true, "layer": "Layer 0"}), json!({"linked": false, "layers": [1, 2]})] {
+        let action = Action::new("A", vec![("layer.linkLayers".into(), params)]);
+        assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+    }
+}
diff --git a/crates/engine/tests/it/main.rs b/crates/engine/tests/it/main.rs
index f6a8360a4f..0535f2e96b 100644
--- a/crates/engine/tests/it/main.rs
+++ b/crates/engine/tests/it/main.rs
@@ -3,6 +3,7 @@
 mod affinity;
 mod artboard_export_names;
 mod atn_crystallize_cell_size;
+mod atn_newer_events;
 mod atn_ripple_amount;
 mod atn_selective_color;
 mod atn_stroke_width;
diff --git a/docs/atn.md b/docs/atn.md
new file mode 100644
index 0000000000..c0a836a735
--- /dev/null
+++ b/docs/atn.md
@@ -0,0 +1,17 @@
+# Photoshop action files
+
+## Targeted layer links
+
+| Photoshop event | Descriptor | PhotoCraft command |
+| --- | --- | --- |
+| `linkSelectedLayers` | `null`: layer target (`Lyr `/`Ordn.Trgt`) | `layer.linkLayers {"linked":true}` |
+| `unlinkSelectedLayers` | `null`: layer target (`Lyr `/`Ordn.Trgt`) | `layer.linkLayers {"linked":false}` |
+
+These events act on the current layer selection. Link keeps an already linked
+selection linked; Unlink keeps an already unlinked selection unlinked. Unlink
+also clears a link group left with only one member. Undo restores the edit.
+
+Omitting `linked` retains the native UI toggle. That ambiguous toggle cannot be
+saved as either Photoshop event. Explicit layer lists and extra parameters also
+cannot be saved as these events. Unsupported targets or extra descriptor keys
+are kept as Photoshop steps for lossless saving, rather than partially replayed.

From c5defb8873ea96cd0ab27efbf2f92eff90a62c4e Mon Sep 17 00:00:00 2001
From: Psychotoxical <171614930+Psychotoxical@users.noreply.github.com>
Date: Sun, 1 Nov 2026 21:56:58 +0100
Subject: [PATCH 015/109] Layers panel: show the filter row in every theme

The filter row (Kind, Name, Mode) was drawn only in the Pro themes, while
Filter Options > Show is in every theme's panel menu, so in Studio,
Classic, Solarized and the others the toggle did nothing.

A hidden filter row no longer filters either: criteria set in Pro used
to keep hiding layers after switching to another theme, with no row to
show or clear them. They are kept and apply again once the row is shown.

Related: #5546, #2729
---
 crates/ui-egui/src/panels/layer_filter_ui.rs  |  5 ++
 .../src/panels/layer_filter_ui/tests.rs       | 52 ++++++++++++++++++-
 crates/ui-egui/src/panels/layers.rs           |  3 +-
 3 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui.rs b/crates/ui-egui/src/panels/layer_filter_ui.rs
index fd035f3284..ba207ef3af 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui.rs
@@ -31,7 +31,12 @@ pub struct Filter {
 }
 
 impl Filter {
+    /// A hidden filter row filters nothing: the criteria stay for when it's shown again, but no
+    /// layer may go missing from the panel without the row that says why.
     pub fn of(ui: &UiState) -> Self {
+        if !ui.layers_panel_options.show_filters {
+            return Self { by: FilterBy::Kind, kinds: Vec::new(), name: String::new(), mode: ui.layer_filter_mode };
+        }
         Self { by: ui.layer_filter_by, kinds: ui.layer_filter.clone(), name: ui.layer_filter_name.clone(), mode: ui.layer_filter_mode }
     }
 
diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index 89e1a6a0b9..ecbdc0d240 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -10,6 +10,7 @@ use serde_json::json;
 use super::{Filter, FilterBy};
 use crate::PhotocraftApp;
 use crate::state::UiState;
+use crate::theme::ThemeKind;
 
 /// Background, "Ink" (Multiply) and "Paper" in a group "Sheets", and "ink notes" (type) on top.
 fn session() -> photocraft_engine::Session {
@@ -91,10 +92,17 @@ fn saved_settings_without_the_new_fields_still_load() {
 }
 
 fn harness() -> Harness<'static, PhotocraftApp> {
+    harness_in(ThemeKind::default())
+}
+
+fn harness_in(theme: ThemeKind) -> Harness<'static, PhotocraftApp> {
     let session = session();
     let mut h = Harness::builder().with_size(vec2(1440.0, 900.0)).with_max_steps(64).build_eframe(move |cc| {
-        PhotocraftApp::setup_context(&cc.egui_ctx, Default::default());
-        PhotocraftApp::new(session, crate::Services::default())
+        PhotocraftApp::setup_context(&cc.egui_ctx, theme);
+        let mut app = PhotocraftApp::new(session, crate::Services::default());
+        app.run("prefs.set", json!({"path": "interface.theme", "value": theme.id()})).unwrap();
+        app.ui.theme = theme;
+        app
     });
     h.run_steps(8);
     h
@@ -136,3 +144,43 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
     h.run_steps(4);
     assert_eq!(drawn(&h), ["ink notes"]);
 }
+
+/// The filter row was drawn in the Pro themes only, while Filter Options › Show is in every
+/// theme's panel menu: in Studio and the others it did nothing.
+#[test]
+fn every_theme_shows_the_filter_row() {
+    for theme in ThemeKind::ALL {
+        let mut h = harness_in(theme);
+        assert!(h.query_by_value("Kind").is_some(), "{theme:?} draws the filter row");
+        h.state_mut().ui.layer_filter = vec!["type".into()];
+        h.run_steps(4);
+        assert_eq!(drawn(&h), ["ink notes"], "{theme:?} filters by kind");
+    }
+}
+
+/// A filter set while the row was shown stops filtering once the row is hidden, so no layer goes
+/// missing without the row that says why; showing the row again brings the filter back.
+#[test]
+fn a_hidden_filter_row_filters_nothing() {
+    let mut h = harness_in(ThemeKind::Studio);
+    h.state_mut().ui.layer_filter = vec!["type".into()];
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["ink notes"]);
+    h.state_mut().ui.layers_panel_options.show_filters = false;
+    h.run_steps(4);
+    assert!(h.query_by_value("Kind").is_none(), "the row is hidden");
+    assert_eq!(drawn(&h), ["ink notes", "Sheets", "Ink", "Paper", "Background"]);
+    assert_eq!(h.state().ui.layer_filter, ["type"], "the criteria are kept");
+    h.state_mut().ui.layers_panel_options.show_filters = true;
+    h.run_steps(4);
+    assert_eq!(drawn(&h), ["ink notes"]);
+}
+
+#[test]
+fn a_hidden_filter_row_makes_the_filter_inactive() {
+    let mut ui = UiState { layer_filter_by: FilterBy::Mode, layer_filter_name: "ink".into(), ..UiState::default() };
+    ui.layer_filter = vec!["pixel".into()];
+    assert!(Filter::of(&ui).active());
+    ui.layers_panel_options.show_filters = false;
+    assert!(!Filter::of(&ui).active());
+}
diff --git a/crates/ui-egui/src/panels/layers.rs b/crates/ui-egui/src/panels/layers.rs
index 176ed271e1..e95ac7db97 100644
--- a/crates/ui-egui/src/panels/layers.rs
+++ b/crates/ui-egui/src/panels/layers.rs
@@ -123,7 +123,8 @@ pub(super) fn layers(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     if !ui.input(|i| i.pointer.primary_down()) || !app.ui.layers_panel_options.preview_on_canvas_when_reordering_layers {
         app.reorder_preview = None;
     }
-    if t.pro && app.ui.layers_panel_options.show_filters {
+    // Every theme draws the filter row: Filter Options › Show is in every theme's panel menu.
+    if app.ui.layers_panel_options.show_filters {
         crate::layer_filter_ui::bar(app, ui);
         ui.add_space(4.0);
     }

From b4c7656c49d60e0cd61de9efef3650386da83bbc Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 13:09:16 -0800
Subject: [PATCH 016/109] feat(engine): replay Smart Object file events from
 ATN

---
 crates/engine/src/cmd/atn_cmds/events.rs   |  69 +++++++-
 crates/engine/src/cmd/atn_cmds/tests.rs    |   4 +
 crates/engine/tests/it/atn_newer_events.rs | 196 ++++++++++++++++++++-
 docs/atn.md                                |  21 +++
 4 files changed, 283 insertions(+), 7 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 67e1aeae75..0e04fb85df 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -1,6 +1,6 @@
 const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly"), ("LghO", "lightenOnly"), ("Anst", "anisotropic")];
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
-use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, ref_class, target_ref};
+use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, path_text, path_value, ref_class, target_ref};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
@@ -178,7 +178,8 @@ fn clipping_to(_: &str, p: &Value) -> Option<Descriptor> {
 // Target matching follows #10628's Link Layers adapter. Recorded Link and Unlink
 // need explicit state: replaying the UI toggle can perform the opposite operation.
 fn link_from(d: &Descriptor, linked: bool) -> Mapped {
-    if *d == desc("null").with("null", target_ref("Lyr ")) {
+    // The reference permits normalizing the top-level descriptor class to null.
+    if d.items == desc("null").with("null", target_ref("Lyr ")).items {
         step("layer.linkLayers", json!({"linked": linked}))
     } else {
         Mapped::Unsupported { harmless: false }
@@ -190,6 +191,38 @@ fn link_to(p: &Value, linked: bool) -> Option<Descriptor> {
     (p.len() == 1 && p.get("linked") == Some(&Value::Bool(linked))).then(|| desc("null").with("null", target_ref("Lyr ")))
 }
 
+fn smart_path_from(d: &Descriptor, id: &str) -> Mapped {
+    let unsupported = Mapped::Unsupported { harmless: false };
+    let key = if id == "layer.smartObjects.convertToLinked" { "Usng" } else { "null" };
+    let Some(path) = d.get(key).and_then(path_text) else { return unsupported };
+    let p = json!({"path": path});
+    let Some(mut expected) = smart_path_to(id, &p) else { return unsupported };
+    if let Some(hint) = d.get("LyrI") {
+        // The reference explicitly omits recording-session IDs on save (#10603,
+        // docs/atn.md:200). They must never become PhotoCraft's playback target.
+        if !matches!(id, "layer.smartObjects.relinkToFile" | "layer.smartObjects.replaceContents") || !matches!(hint, D::Integer(n) if *n > 0) {
+            return unsupported;
+        }
+        expected = expected.with("LyrI", hint.clone());
+    }
+    // Normalize the top-level header as Open/Place do, but refuse unknown keys,
+    // targets and path encodings rather than partly replaying them.
+    if d.items == expected.items { step(id, p) } else { unsupported }
+}
+
+fn smart_path_to(id: &str, p: &Value) -> Option<Descriptor> {
+    let p = p.as_object()?;
+    let path = p.get("path")?.as_str()?;
+    if p.len() != 1 || path.is_empty() || path.contains('\0') {
+        return None;
+    }
+    Some(if id == "layer.smartObjects.convertToLinked" {
+        desc("null").with("null", target_ref("Lyr ")).with("Usng", path_value(path))
+    } else {
+        desc("null").with("null", path_value(path))
+    })
+}
+
 /// A clipping mask event: `clipping_from` / `clipping_to` with one command id.
 macro_rules! clipping_event {
     ($code:literal, $name:literal, $label:literal, $id:literal) => {
@@ -496,6 +529,38 @@ pub(super) const EVENTS: &[Event] = &[
     ev!("", "newPlacedLayer", "Convert to Smart Object", "layer.smartObjects.convertToSmartObject", &[]),
     ev!("", "placedLayerEditContents", "Edit Contents", "layer.smartObjects.editContents", &[]),
     ev!("", "updatePlacedLayer", "Update Smart Objects", "layer.smartObjects.updateModifiedContent", &[]),
+    Event {
+        code: "",
+        name: "placedLayerExportContents",
+        label: "Export Contents",
+        ids: &["layer.smartObjects.exportContents"],
+        from: |d| smart_path_from(d, "layer.smartObjects.exportContents"),
+        to: smart_path_to,
+    },
+    Event {
+        code: "",
+        name: "placedLayerConvertToLinked",
+        label: "Convert to Linked",
+        ids: &["layer.smartObjects.convertToLinked"],
+        from: |d| smart_path_from(d, "layer.smartObjects.convertToLinked"),
+        to: smart_path_to,
+    },
+    Event {
+        code: "",
+        name: "placedLayerRelinkToFile",
+        label: "Relink to File",
+        ids: &["layer.smartObjects.relinkToFile"],
+        from: |d| smart_path_from(d, "layer.smartObjects.relinkToFile"),
+        to: smart_path_to,
+    },
+    Event {
+        code: "",
+        name: "placedLayerReplaceContents",
+        label: "Replace Contents",
+        ids: &["layer.smartObjects.replaceContents"],
+        from: |d| smart_path_from(d, "layer.smartObjects.replaceContents"),
+        to: smart_path_to,
+    },
     Event { code: "Hd  ", name: "hide", label: "Hide", ids: &["layer.hideLayers"], from: |d| visibility_from(d, "layer.hideLayers"), to: visibility_to },
     Event { code: "Shw ", name: "show", label: "Show", ids: &["layer.showLayers"], from: |d| visibility_from(d, "layer.showLayers"), to: visibility_to },
     Event {
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 8680429482..5975f03bc1 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -621,6 +621,10 @@ fn every_mapped_command_exports_and_imports_back() {
         ("layer.smartObjects.convertToSmartObject", json!({})),
         ("layer.smartObjects.editContents", json!({})),
         ("layer.smartObjects.updateModifiedContent", json!({})),
+        ("layer.smartObjects.exportContents", json!({"path": "/tmp/contents.png"})),
+        ("layer.smartObjects.convertToLinked", json!({"path": "/tmp/linked.png"})),
+        ("layer.smartObjects.relinkToFile", json!({"path": "/tmp/relinked.png"})),
+        ("layer.smartObjects.replaceContents", json!({"path": "/tmp/replacement.png"})),
         ("paint.bucket", json!({"x": 10, "y": 20, "tolerance": 32, "antiAlias": true, "contiguous": false, "opacity": 100})),
         ("image.imageSize", json!({"percent": 200, "resample": "bicubicAutomatic"})),
         ("file.placeEmbedded", json!({"path": "/tmp/logo.png", "scale": 50})),
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 5b56235657..a4cf68bb2c 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -1,5 +1,5 @@
 //! #10700: recorded Link and Unlink must not replay as a state-dependent toggle.
-use photocraft_doc::{Layer, LayerId};
+use photocraft_doc::{Layer, LayerContent, LayerId, SmartObject, SmartSource};
 use photocraft_engine::{Session, actions_cmds::Action, atn_cmds};
 use photocraft_psd::{
     atn::{self, AtnAction, AtnEvent, AtnFile, AtnItem},
@@ -32,8 +32,12 @@ fn groups(s: &Session) -> Vec<Option<u64>> {
 }
 
 fn target() -> D {
+    target_class("Lyr ")
+}
+
+fn target_class(class_id: &str) -> D {
     D::Reference(vec![ReferenceItem::Enumerated {
-        class: Class { name: UnicodeString::new_nul(""), class_id: Id::new("Lyr ") },
+        class: Class { name: UnicodeString::new_nul(""), class_id: Id::new(class_id) },
         type_id: Id::new("Ordn"),
         value: Id::new("Trgt"),
     }])
@@ -57,6 +61,12 @@ fn load(s: &mut Session, bytes: &[u8]) -> serde_json::Value {
     s.execute("actions.load", json!({"data": photocraft_engine::paint::tile::b64_encode(bytes)})).unwrap()
 }
 
+fn play(s: &mut Session) {
+    let report = s.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+    assert!(report.get("failed").is_none(), "{report}");
+    assert_eq!(report["ran"], 1, "{report}");
+}
+
 #[test]
 fn explicit_links_are_idempotent_and_omitted_state_still_toggles() {
     let mut s = fixture(&[None, None], &[0, 1]);
@@ -138,7 +148,7 @@ fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
             assert_eq!(parsed.actions[0].items[0].descriptor, Some(descriptor));
             let mut replay = fixture(&initial, &[0, 1]);
             assert_eq!(load(&mut replay, &bytes)["unsupported"], json!([]));
-            replay.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+            play(&mut replay);
             if linked {
                 let result = groups(&replay);
                 assert!(result[0].is_some());
@@ -149,7 +159,7 @@ fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
             }
             let before = replay.active().unwrap().doc.clone();
             let history = replay.active().unwrap().history.past_len();
-            replay.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+            play(&mut replay);
             assert_eq!(replay.active().unwrap().doc, before);
             assert_eq!(replay.active().unwrap().history.past_len(), history);
         }
@@ -162,7 +172,7 @@ fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
         for descriptor in [
             Descriptor::new("null"),
             Descriptor::new("null").with("null", D::Integer(1)),
-            Descriptor::new("other").with("null", target()),
+            Descriptor::new("null").with("null", target_class("Dcmn")),
             Descriptor::new("null").with("null", target()).with("extra", D::Boolean(true)),
             Descriptor::new("null").with("null", target()).with("null", target()),
         ] {
@@ -180,3 +190,179 @@ fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
         assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
     }
 }
+
+#[test]
+fn link_descriptor_headers_normalize_without_changing_meaningful_keys() {
+    for event in ["linkSelectedLayers", "unlinkSelectedLayers"] {
+        let mut s = Session::new();
+        let descriptor = Descriptor::new(event).with("null", target());
+        assert_eq!(load(&mut s, &file(event, descriptor))["unsupported"], json!([]));
+        let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+        let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+        let parsed = atn::parse(&bytes).unwrap();
+        assert_eq!(parsed.actions[0].items[0].event, AtnEvent::name(event));
+        assert_eq!(parsed.actions[0].items[0].descriptor, Some(Descriptor::new("null").with("null", target())));
+    }
+}
+
+const SMART_PATHS: &[(&str, &str)] = &[
+    ("placedLayerExportContents", "layer.smartObjects.exportContents"),
+    ("placedLayerConvertToLinked", "layer.smartObjects.convertToLinked"),
+    ("placedLayerRelinkToFile", "layer.smartObjects.relinkToFile"),
+    ("placedLayerReplaceContents", "layer.smartObjects.replaceContents"),
+];
+
+fn path_value(path: &str) -> D {
+    let units: Vec<_> = path.encode_utf16().chain(std::iter::once(0)).collect();
+    let mut bytes = b"txtu".to_vec();
+    bytes.extend_from_slice(&u32::try_from(12 + units.len() * 2).unwrap().to_le_bytes());
+    bytes.extend_from_slice(&u32::try_from(units.len()).unwrap().to_le_bytes());
+    bytes.extend(units.iter().flat_map(|unit| unit.to_le_bytes()));
+    D::Path(bytes)
+}
+
+fn smart_path_descriptor(event: &str, path: &str) -> Descriptor {
+    if event == "placedLayerConvertToLinked" {
+        Descriptor::new("null").with("null", target()).with("Usng", path_value(path))
+    } else {
+        Descriptor::new("null").with("null", path_value(path))
+    }
+}
+
+fn png(color: &str) -> Vec<u8> {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 4, "height": 4, "background": color})).unwrap();
+    photocraft_io::export(&s.active().unwrap().doc, "png", &Default::default()).unwrap().bytes
+}
+
+fn smart_fixture(bytes: &[u8]) -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 4, "height": 4})).unwrap();
+    photocraft_engine::file_cmds::place_bytes(&mut s, "original.png", bytes.to_vec(), None, &json!({})).unwrap();
+    s
+}
+
+fn active_smart(s: &Session) -> &SmartObject {
+    let st = s.active().unwrap();
+    let LayerContent::Smart(smart) = &st.doc.layer(st.active_layer.unwrap()).unwrap().content else { panic!("expected a Smart Object") };
+    smart
+}
+
+fn assert_smart_file_output(event: &str, s: &Session, path: &str, original: &[u8], replacement: &[u8]) {
+    match event {
+        "placedLayerExportContents" => assert_eq!(std::fs::read(path).unwrap().as_slice(), original),
+        "placedLayerConvertToLinked" => {
+            assert_eq!(std::fs::read(path).unwrap().as_slice(), original);
+            assert!(matches!(&active_smart(s).source, SmartSource::Linked { path: actual } if actual == path));
+        }
+        "placedLayerRelinkToFile" => assert!(matches!(&active_smart(s).source, SmartSource::Linked { path: actual } if actual == path)),
+        "placedLayerReplaceContents" => {
+            assert!(matches!(&active_smart(s).source, SmartSource::Embedded { bytes, .. } if bytes.as_slice() == replacement));
+        }
+        _ => unreachable!(),
+    }
+}
+
+#[test]
+fn smart_paths_roundtrip_and_play_real_files_on_the_current_target() {
+    let original = png("#0000ff");
+    let replacement = png("#ff0000");
+    for &(event, id) in SMART_PATHS {
+        for header in ["null", event] {
+            let dir = tempfile::tempdir().unwrap();
+            let path = dir.path().join("contents Ω.png");
+            let path = path.to_str().unwrap();
+            let replacing = matches!(event, "placedLayerRelinkToFile" | "placedLayerReplaceContents");
+            if replacing {
+                std::fs::write(path, &replacement).unwrap();
+            }
+            let canonical = smart_path_descriptor(event, path);
+            let mut recorded = canonical.clone();
+            recorded.class_id = Id::new(header);
+            let mut s = smart_fixture(&original);
+            if replacing {
+                let hint = i32::MAX;
+                assert!(s.active().unwrap().doc.walk().iter().all(|(_, _, layer)| layer.id.0 != hint as u64));
+                recorded = recorded.with("LyrI", D::Integer(hint));
+            }
+            assert_eq!(load(&mut s, &file(event, recorded))["unsupported"], json!([]), "{event}");
+            assert_eq!(s.actions.list[0].steps, [(id.to_string(), json!({"path": path}))]);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            assert_eq!(saved["skipped"], json!([]));
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            let parsed = atn::parse(&bytes).unwrap();
+            assert_eq!(parsed.actions[0].items[0].event, AtnEvent::name(event));
+            // Reference #10603, docs/atn.md:197–201: normalize the descriptor class,
+            // and omit session LyrI. All meaningful event/path keys remain identical.
+            assert_eq!(parsed.actions[0].items[0].descriptor, Some(canonical));
+            assert_eq!(load(&mut s, &bytes)["unsupported"], json!([]));
+            let before = s.active().unwrap().doc.clone();
+            let before_smart = active_smart(&s).clone();
+            play(&mut s);
+            assert_eq!(active_smart(&s).transform, before_smart.transform);
+            assert_smart_file_output(event, &s, path, &original, &replacement);
+            if replacing {
+                assert!(photocraft_compose::flatten(&s.active().unwrap().doc).px.iter().all(|px| *px == [1.0, 0.0, 0.0, 1.0]));
+            }
+            if event == "placedLayerExportContents" {
+                assert_eq!(s.active().unwrap().doc, before);
+            } else {
+                assert!(s.undo());
+                assert_eq!(s.active().unwrap().doc, before);
+            }
+        }
+    }
+}
+
+#[test]
+fn smart_paths_keep_missing_unusable_and_unrepresented_descriptors_whole() {
+    for &(event, _) in SMART_PATHS {
+        let key = if event == "placedLayerConvertToLinked" { "Usng" } else { "null" };
+        for descriptor in [
+            Descriptor::new("null"),
+            Descriptor::new("null").with(key, path_value("")),
+            Descriptor::new("null").with(key, path_value("a\0b")),
+            Descriptor::new("null").with(key, D::Text(UnicodeString::new("/tmp/file.png"))),
+            Descriptor::new("null").with(key, D::Path(b"txtu".to_vec())),
+            Descriptor::new("null").with("Usng", path_value("/tmp/file.png")),
+            smart_path_descriptor(event, "/tmp/file.png").with("extra", D::Integer(1)),
+            smart_path_descriptor(event, "/tmp/file.png").with("LyrI", D::Boolean(true)),
+            smart_path_descriptor(event, "/tmp/file.png").with("LyrI", D::Integer(-1)),
+            smart_path_descriptor(event, "/tmp/file.png").with("LyrI", D::LargeInteger(i64::from(i32::MAX) + 1)),
+        ] {
+            let mut s = Session::new();
+            assert_eq!(load(&mut s, &file(event, descriptor.clone()))["unsupported"].as_array().unwrap().len(), 1);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            assert_eq!(atn::parse(&bytes).unwrap().actions[0].items[0].descriptor, Some(descriptor));
+        }
+    }
+}
+
+#[test]
+fn smart_path_exports_refuse_unrepresentable_native_params() {
+    for &(_, id) in SMART_PATHS {
+        for params in [json!({}), json!({"path": ""}), json!({"path": "a\0b"}), json!({"path": 3}), json!({"path": "/tmp/a.png", "layer": 1})] {
+            let action = Action::new("A", vec![(id.into(), params)]);
+            assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+        }
+    }
+}
+
+#[test]
+fn unusable_smart_file_at_playback_fails_without_changing_the_document() {
+    let original = png("#0000ff");
+    let dir = tempfile::tempdir().unwrap();
+    for &(event, id) in SMART_PATHS {
+        let mut s = smart_fixture(&original);
+        assert_eq!(load(&mut s, &file(event, smart_path_descriptor(event, dir.path().to_str().unwrap())))["unsupported"], json!([]));
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        let report = s.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+        assert_eq!(report["ran"], 0, "{event}: {report}");
+        assert_eq!(report["failed"]["id"], id, "{event}: {report}");
+        assert!(report["failed"]["error"].as_str().is_some_and(|error| !error.is_empty()), "{event}: {report}");
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+}
diff --git a/docs/atn.md b/docs/atn.md
index c0a836a735..727a5c30c6 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -15,3 +15,24 @@ Omitting `linked` retains the native UI toggle. That ambiguous toggle cannot be
 saved as either Photoshop event. Explicit layer lists and extra parameters also
 cannot be saved as these events. Unsupported targets or extra descriptor keys
 are kept as Photoshop steps for lossless saving, rather than partially replayed.
+
+## Smart Object file operations
+
+| Photoshop event | Meaningful descriptor keys | PhotoCraft command |
+| --- | --- | --- |
+| `placedLayerExportContents` | `null`: path | `layer.smartObjects.exportContents` |
+| `placedLayerConvertToLinked` | `null`: target layer; `Usng`: path | `layer.smartObjects.convertToLinked` |
+| `placedLayerRelinkToFile` | `null`: path | `layer.smartObjects.relinkToFile` |
+| `placedLayerReplaceContents` | `null`: path | `layer.smartObjects.replaceContents` |
+
+The path uses the same `Pth `/`txtu` encoding as Open and Place. Missing,
+undecodable or unrepresented path options are kept as complete Photoshop steps.
+Native steps aimed at explicit layers or carrying extra options cannot be saved
+as these targeted events. File access occurs during playback through the native
+command; a missing or unusable file produces that command's error.
+
+The reference explicitly permits normalizing the top-level descriptor class to
+`null` and omitting recording-session IDs on save. Relink and Replace accept a
+recorded integer `LyrI` as a session hint; it does not select a PhotoCraft layer.
+Playback operates on the current Smart Object. The hint is omitted on save,
+while the event, path and other meaningful keys are retained.

From 71b98c813421decd855880eb2d613fc78531fc7f Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 13:36:08 -0800
Subject: [PATCH 017/109] feat(engine): replay target-only ATN menu events

---
 crates/engine/src/cmd/atn_cmds/events.rs   |  78 +++++-
 crates/engine/src/cmd/atn_cmds/tests.rs    |  16 ++
 crates/engine/tests/it/atn_newer_events.rs | 270 ++++++++++++++++++++-
 docs/atn.md                                |  28 +++
 4 files changed, 380 insertions(+), 12 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 0e04fb85df..cca7d2d69c 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -17,7 +17,7 @@ use super::steps_layer::{
 };
 use super::steps_make::{locking_from, locking_to, make_from, make_to, set_from, set_to};
 use super::tables::{NOISE, OFFSET_FILL, SMART_BLUR_MODE, SMART_BLUR_QUALITY, TRIM};
-use super::{AtnEvent, D, Descriptor, STOP_MESSAGE, Value, json};
+use super::{AtnEvent, D, Descriptor, Map, STOP_MESSAGE, Value, json};
 
 /// An event: code (empty when Photoshop only has a string name), string name, the panel
 /// label, the command ids it exports (the first is the one simple events import to), and the
@@ -175,20 +175,57 @@ fn clipping_to(_: &str, p: &Value) -> Option<Descriptor> {
     Some(desc("null").with("null", layer_ref(p)?))
 }
 
-// Target matching follows #10628's Link Layers adapter. Recorded Link and Unlink
-// need explicit state: replaying the UI toggle can perform the opposite operation.
-fn link_from(d: &Descriptor, linked: bool) -> Mapped {
-    // The reference permits normalizing the top-level descriptor class to null.
-    if d.items == desc("null").with("null", target_ref("Lyr ")).items {
-        step("layer.linkLayers", json!({"linked": linked}))
-    } else {
-        Mapped::Unsupported { harmless: false }
+// Adapter-only transport bit: the reference permits either no target key or the
+// current-layer target. Save must retain that distinction; native behavior is identical.
+const NO_TARGET: &str = "_atnNoTarget";
+
+fn target_params(d: &Descriptor) -> Option<Map<String, Value>> {
+    let mut p = Map::new();
+    if d.items.is_empty() {
+        p.insert(NO_TARGET.into(), Value::Bool(true));
+    } else if d.items != desc("null").with("null", target_ref("Lyr ")).items {
+        return None;
+    }
+    Some(p)
+}
+
+fn target_descriptor(p: &Value) -> Option<Descriptor> {
+    match p.get(NO_TARGET) {
+        None => Some(desc("null").with("null", target_ref("Lyr "))),
+        Some(Value::Bool(true)) => Some(desc("null")),
+        Some(_) => None,
     }
 }
 
+// Native-parameter allowlist adapted from #10628; refuse unrepresented options on export.
+fn params(p: &Value, allowed: &[&str]) -> bool {
+    p.as_object().is_some_and(|p| p.keys().all(|key| allowed.contains(&key.as_str())))
+}
+
+fn target_only_from(d: &Descriptor, id: &str) -> Mapped {
+    target_params(d).map_or(Mapped::Unsupported { harmless: false }, |p| step(id, Value::Object(p)))
+}
+
+fn target_only_to(_: &str, p: &Value) -> Option<Descriptor> {
+    if !params(p, &[NO_TARGET]) {
+        return None;
+    }
+    target_descriptor(p)
+}
+
+// Recorded Link and Unlink need explicit state: replaying the UI toggle can
+// perform the opposite operation. Target matching follows #10628's adapter.
+fn link_from(d: &Descriptor, linked: bool) -> Mapped {
+    let Some(mut p) = target_params(d) else { return Mapped::Unsupported { harmless: false } };
+    p.insert("linked".into(), Value::Bool(linked));
+    step("layer.linkLayers", Value::Object(p))
+}
+
 fn link_to(p: &Value, linked: bool) -> Option<Descriptor> {
-    let p = p.as_object()?;
-    (p.len() == 1 && p.get("linked") == Some(&Value::Bool(linked))).then(|| desc("null").with("null", target_ref("Lyr ")))
+    if !params(p, &["linked", NO_TARGET]) || p.get("linked") != Some(&Value::Bool(linked)) {
+        return None;
+    }
+    target_descriptor(p)
 }
 
 fn smart_path_from(d: &Descriptor, id: &str) -> Mapped {
@@ -230,6 +267,12 @@ macro_rules! clipping_event {
     };
 }
 
+macro_rules! target_event {
+    ($name:literal, $label:literal, $id:literal) => {
+        Event { code: "", name: $name, label: $label, ids: &[$id], from: |d| target_only_from(d, $id), to: target_only_to }
+    };
+}
+
 /// Every Photoshop event PhotoCraft maps. The order matters only for the panel label.
 pub(super) const EVENTS: &[Event] = &[
     // Filters.
@@ -401,6 +444,15 @@ pub(super) const EVENTS: &[Event] = &[
     },
     Event { code: "Dplc", name: "duplicate", label: "Duplicate", ids: &["layer.duplicate", "image.duplicate"], from: duplicate_from, to: duplicate_to },
     // Layers.
+    target_event!("reverse", "Reverse", "layer.arrange.reverse"),
+    target_event!("selectLinkedLayers", "Select Linked Layers", "layer.selectLinkedLayers"),
+    target_event!("disableLayerStyle", "Clear Layer Style", "layer.layerStyle.clear"),
+    target_event!("rasterizeAll", "Rasterize All Layers", "layer.rasterize.allLayers"),
+    target_event!("addBlankVideoLayer", "New Blank Video Layer", "layer.videoLayers.newBlankVideoLayer"),
+    target_event!("isolateLayers", "Isolate Layers", "select.isolateLayers"),
+    target_event!("textLoadDefaultTypeStyles", "Load Default Type Styles", "type.loadDefaultTypeStyles"),
+    target_event!("textSaveDefaultTypeStyles", "Save Default Type Styles", "type.saveDefaultTypeStyles"),
+    target_event!("recordMeasurements", "Record Measurements", "image.analysis.recordMeasurements"),
     Event { code: "", name: "linkSelectedLayers", label: "Link Layers", ids: &["layer.linkLayers"], from: |d| link_from(d, true), to: |_, p| link_to(p, true) },
     Event {
         code: "",
@@ -529,6 +581,10 @@ pub(super) const EVENTS: &[Event] = &[
     ev!("", "newPlacedLayer", "Convert to Smart Object", "layer.smartObjects.convertToSmartObject", &[]),
     ev!("", "placedLayerEditContents", "Edit Contents", "layer.smartObjects.editContents", &[]),
     ev!("", "updatePlacedLayer", "Update Smart Objects", "layer.smartObjects.updateModifiedContent", &[]),
+    target_event!("placedLayerMakeCopy", "New Smart Object via Copy", "layer.smartObjects.newSmartObjectViaCopy"),
+    target_event!("placedLayerConvertToLayers", "Convert to Layers", "layer.smartObjects.convertToLayers"),
+    target_event!("placedLayerConvertToEmbedded", "Convert to Embedded", "layer.smartObjects.convertToEmbedded"),
+    target_event!("placedLayerUpdateAllModified", "Update All Modified Content", "layer.smartObjects.updateAllModifiedContent"),
     Event {
         code: "",
         name: "placedLayerExportContents",
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 5975f03bc1..965399241c 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -550,6 +550,18 @@ fn every_mapped_command_exports_and_imports_back() {
         ("layer.groupLayers", json!({})),
         ("layer.linkLayers", json!({"linked": true})),
         ("layer.linkLayers", json!({"linked": false})),
+        ("layer.linkLayers", json!({"linked": true, "_atnNoTarget": true})),
+        ("layer.linkLayers", json!({"linked": false, "_atnNoTarget": true})),
+        ("layer.arrange.reverse", json!({})),
+        ("layer.arrange.reverse", json!({"_atnNoTarget": true})),
+        ("layer.selectLinkedLayers", json!({})),
+        ("layer.layerStyle.clear", json!({})),
+        ("layer.rasterize.allLayers", json!({})),
+        ("layer.videoLayers.newBlankVideoLayer", json!({})),
+        ("select.isolateLayers", json!({})),
+        ("type.loadDefaultTypeStyles", json!({})),
+        ("type.saveDefaultTypeStyles", json!({})),
+        ("image.analysis.recordMeasurements", json!({})),
         ("layer.new.layerViaCopy", json!({})),
         ("layer.newFillLayer.solidColor", json!({"color": "#336699"})),
         ("layer.newAdjustmentLayer.hueSaturation", json!({})),
@@ -621,6 +633,10 @@ fn every_mapped_command_exports_and_imports_back() {
         ("layer.smartObjects.convertToSmartObject", json!({})),
         ("layer.smartObjects.editContents", json!({})),
         ("layer.smartObjects.updateModifiedContent", json!({})),
+        ("layer.smartObjects.newSmartObjectViaCopy", json!({})),
+        ("layer.smartObjects.convertToLayers", json!({})),
+        ("layer.smartObjects.convertToEmbedded", json!({})),
+        ("layer.smartObjects.updateAllModifiedContent", json!({})),
         ("layer.smartObjects.exportContents", json!({"path": "/tmp/contents.png"})),
         ("layer.smartObjects.convertToLinked", json!({"path": "/tmp/linked.png"})),
         ("layer.smartObjects.relinkToFile", json!({"path": "/tmp/relinked.png"})),
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index a4cf68bb2c..70db016186 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -170,7 +170,7 @@ fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
 fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
     for event in ["linkSelectedLayers", "unlinkSelectedLayers"] {
         for descriptor in [
-            Descriptor::new("null"),
+            Descriptor::new("null").with("null", D::Reference(vec![])),
             Descriptor::new("null").with("null", D::Integer(1)),
             Descriptor::new("null").with("null", target_class("Dcmn")),
             Descriptor::new("null").with("null", target()).with("extra", D::Boolean(true)),
@@ -191,6 +191,274 @@ fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
     }
 }
 
+const TARGET_EVENTS: &[(&str, &str)] = &[
+    ("reverse", "layer.arrange.reverse"),
+    ("selectLinkedLayers", "layer.selectLinkedLayers"),
+    ("disableLayerStyle", "layer.layerStyle.clear"),
+    ("placedLayerMakeCopy", "layer.smartObjects.newSmartObjectViaCopy"),
+    ("placedLayerConvertToLayers", "layer.smartObjects.convertToLayers"),
+    ("placedLayerConvertToEmbedded", "layer.smartObjects.convertToEmbedded"),
+    ("placedLayerUpdateAllModified", "layer.smartObjects.updateAllModifiedContent"),
+    ("rasterizeAll", "layer.rasterize.allLayers"),
+    ("addBlankVideoLayer", "layer.videoLayers.newBlankVideoLayer"),
+    ("isolateLayers", "select.isolateLayers"),
+    ("textLoadDefaultTypeStyles", "type.loadDefaultTypeStyles"),
+    ("textSaveDefaultTypeStyles", "type.saveDefaultTypeStyles"),
+    ("recordMeasurements", "image.analysis.recordMeasurements"),
+];
+
+fn targeted(event: &str, explicit: bool) -> Descriptor {
+    let d = Descriptor::new(event);
+    if explicit { d.with("null", target()) } else { d }
+}
+
+fn load_targeted(s: &mut Session, event: &str, id: &str, explicit: bool) {
+    assert_eq!(load(s, &file(event, targeted(event, explicit)))["unsupported"], json!([]), "{event}");
+    let p = if explicit { json!({}) } else { json!({"_atnNoTarget": true}) };
+    assert_eq!(s.actions.list[0].steps, [(id.into(), p)]);
+}
+
+#[test]
+fn target_events_keep_empty_and_explicit_target_descriptors_distinct() {
+    for &(event, id) in TARGET_EVENTS {
+        for explicit in [false, true] {
+            let mut s = Session::new();
+            load_targeted(&mut s, event, id, explicit);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            let item = &atn::parse(&bytes).unwrap().actions[0].items[0];
+            assert_eq!(item.event, AtnEvent::name(event));
+            assert_eq!(item.descriptor, Some(targeted("null", explicit)), "{event}");
+            assert_eq!(load(&mut s, &bytes)["unsupported"], json!([]));
+        }
+    }
+    // Reference lines197–199 permits writing an empty descriptor for an absent one.
+    let mut f = atn::parse(&file("reverse", Descriptor::new("null"))).unwrap();
+    f.actions[0].items[0].descriptor = None;
+    let mut s = Session::new();
+    assert_eq!(load(&mut s, &atn::write(&f).unwrap())["unsupported"], json!([]));
+    let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+    let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+    assert_eq!(atn::parse(&bytes).unwrap().actions[0].items[0].descriptor, Some(Descriptor::new("null")));
+}
+
+#[test]
+fn bare_link_events_keep_their_operation_and_empty_keys() {
+    for (event, linked) in [("linkSelectedLayers", true), ("unlinkSelectedLayers", false)] {
+        let initial = if linked { None } else { Some(77) };
+        let mut s = fixture(&[initial, initial], &[0, 1]);
+        assert_eq!(load(&mut s, &file(event, Descriptor::new(event)))["unsupported"], json!([]));
+        assert_eq!(s.actions.list[0].steps[0].1, json!({"linked": linked, "_atnNoTarget": true}));
+        let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+        let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+        assert_eq!(atn::parse(&bytes).unwrap().actions[0].items[0].descriptor, Some(Descriptor::new("null")));
+        let before = s.active().unwrap().doc.clone();
+        play(&mut s);
+        assert_ne!(s.active().unwrap().doc, before);
+        let after = s.active().unwrap().doc.clone();
+        assert!(groups(&s).iter().all(|group| group.is_some() == linked));
+        assert_eq!(groups(&s)[0], groups(&s)[1]);
+        play(&mut s);
+        assert_eq!(s.active().unwrap().doc, after);
+    }
+}
+
+#[test]
+fn target_events_keep_unknown_targets_and_refuse_native_options() {
+    for &(event, id) in TARGET_EVENTS {
+        for descriptor in [
+            Descriptor::new(event).with("null", D::Integer(1)),
+            Descriptor::new(event).with("null", target_class("Dcmn")),
+            targeted(event, true).with("null", target()),
+            targeted(event, true).with("extra", D::Boolean(true)),
+        ] {
+            let mut s = Session::new();
+            assert_eq!(load(&mut s, &file(event, descriptor.clone()))["unsupported"].as_array().unwrap().len(), 1);
+            let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+            let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+            assert_eq!(atn::parse(&bytes).unwrap().actions[0].items[0].descriptor, Some(descriptor));
+        }
+        for p in [json!({"layer": 1}), json!({"on": true}), json!({"_atnNoTarget": false}), json!({"_atnNoTarget": "true"})] {
+            let action = Action::new("A", vec![(id.into(), p)]);
+            assert!(atn_cmds::export("Links", &[&action], &[], false).is_err(), "{event}");
+        }
+    }
+    for linked in [false, true] {
+        let action = Action::new("A", vec![("layer.linkLayers".into(), json!({"linked": linked, "_atnNoTarget": false}))]);
+        assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+    }
+}
+
+#[test]
+fn reverse_linked_selection_and_clear_style_events_do_their_edits() {
+    for explicit in [false, true] {
+        let mut s = fixture(&[None, None, None], &[0, 1, 2]);
+        let before = s.active().unwrap().doc.clone();
+        let ids: Vec<_> = before.layers.iter().map(|layer| layer.id).rev().collect();
+        load_targeted(&mut s, "reverse", "layer.arrange.reverse", explicit);
+        play(&mut s);
+        assert_eq!(s.active().unwrap().doc.layers.iter().map(|layer| layer.id).collect::<Vec<_>>(), ids);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+
+        let mut s = fixture(&[Some(77), Some(77), None], &[0]);
+        let ids: Vec<_> = s.active().unwrap().doc.layers[..2].iter().map(|layer| layer.id).collect();
+        load_targeted(&mut s, "selectLinkedLayers", "layer.selectLinkedLayers", explicit);
+        play(&mut s);
+        assert_eq!(s.active().unwrap().selected_layers(), ids);
+
+        let mut s = fixture(&[None], &[0]);
+        s.execute("layer.layerStyle.colorOverlay", json!({"color": "#ff0000"})).unwrap();
+        let before = s.active().unwrap().doc.clone();
+        assert_eq!(before.layers[0].effects.items.len(), 1);
+        load_targeted(&mut s, "disableLayerStyle", "layer.layerStyle.clear", explicit);
+        play(&mut s);
+        assert!(s.active().unwrap().doc.layers[0].effects.items.is_empty());
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+fn smart_target_scene(event: &str, bytes: &[u8], replacement: &[u8], path: &str) -> Session {
+    let mut s = smart_fixture(bytes);
+    if matches!(event, "placedLayerConvertToEmbedded" | "placedLayerUpdateAllModified") {
+        s.execute("layer.smartObjects.convertToLinked", json!({"path": path})).unwrap();
+    }
+    if event == "placedLayerUpdateAllModified" {
+        std::fs::write(path, replacement).unwrap();
+    }
+    s
+}
+
+fn assert_smart_target_edit(event: &str, s: &Session, original_id: photocraft_doc::SmartContentsId, pixels: &[[f32; 4]], bytes: &[u8]) {
+    match event {
+        "placedLayerMakeCopy" => {
+            assert_ne!(active_smart(s).contents_id, original_id);
+            assert_eq!(s.active().unwrap().doc.walk().iter().filter(|(_, _, layer)| matches!(layer.content, LayerContent::Smart(_))).count(), 2);
+        }
+        "placedLayerConvertToLayers" => assert!(s.active().unwrap().doc.walk().iter().all(|(_, _, layer)| !matches!(layer.content, LayerContent::Smart(_)))),
+        "placedLayerConvertToEmbedded" => assert!(matches!(&active_smart(s).source, SmartSource::Embedded { bytes: actual, .. } if actual.as_slice() == bytes)),
+        "placedLayerUpdateAllModified" => assert!(photocraft_compose::flatten(&s.active().unwrap().doc).px.iter().all(|px| *px == [1.0, 0.0, 0.0, 1.0])),
+        _ => unreachable!(),
+    }
+    if event != "placedLayerUpdateAllModified" {
+        assert_eq!(photocraft_compose::flatten(&s.active().unwrap().doc).px, pixels);
+    }
+}
+
+#[test]
+fn smart_target_events_copy_unpack_embed_and_refresh_real_contents() {
+    let original = png("#0000ff");
+    let replacement = png("#ff0000");
+    for &(event, id) in &TARGET_EVENTS[3..7] {
+        for explicit in [false, true] {
+            let dir = tempfile::tempdir().unwrap();
+            let path = dir.path().join("linked.png");
+            let mut s = smart_target_scene(event, &original, &replacement, path.to_str().unwrap());
+            let before = s.active().unwrap().doc.clone();
+            let pixels = photocraft_compose::flatten(&before).px;
+            let contents_id = active_smart(&s).contents_id;
+            load_targeted(&mut s, event, id, explicit);
+            play(&mut s);
+            assert_smart_target_edit(event, &s, contents_id, &pixels, &original);
+            assert!(s.undo());
+            assert_eq!(s.active().unwrap().doc, before);
+        }
+    }
+}
+
+#[test]
+fn rasterize_all_event_visits_nested_and_top_level_smart_layers() {
+    for explicit in [false, true] {
+        let mut s = smart_fixture(&png("#0000ff"));
+        let first = s.active().unwrap().active_layer.unwrap();
+        s.execute("layer.smartObjects.newSmartObjectViaCopy", json!({})).unwrap();
+        let doc = Arc::make_mut(&mut s.active_mut().unwrap().doc);
+        let nested = doc.remove(first).unwrap();
+        doc.layers.push(Layer::group("Nested", vec![nested]));
+        let before = s.active().unwrap().doc.clone();
+        let pixels = photocraft_compose::flatten(&before).px;
+        load_targeted(&mut s, "rasterizeAll", "layer.rasterize.allLayers", explicit);
+        play(&mut s);
+        assert!(s.active().unwrap().doc.walk().iter().all(|(_, _, layer)| !matches!(layer.content, LayerContent::Smart(_))));
+        assert_eq!(photocraft_compose::flatten(&s.active().unwrap().doc).px, pixels);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+#[test]
+fn video_and_isolate_events_use_current_document_state() {
+    for explicit in [false, true] {
+        let mut s = fixture(&[None], &[0]);
+        let before = s.active().unwrap().doc.clone();
+        load_targeted(&mut s, "addBlankVideoLayer", "layer.videoLayers.newBlankVideoLayer", explicit);
+        play(&mut s);
+        let st = s.active().unwrap();
+        let video = st.doc.layer(st.active_layer.unwrap()).unwrap().video.as_ref().unwrap();
+        assert_eq!(video.frames.len(), 1);
+        assert_eq!(video.fps, 30.0);
+        assert!(video.frames[0].content_bounds().is_empty());
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+
+        let mut s = fixture(&[None, None, None], &[0, 2]);
+        let before = s.active().unwrap().doc.clone();
+        let ids = s.active().unwrap().selected_layers();
+        let history = s.active().unwrap().history.past_len();
+        load_targeted(&mut s, "isolateLayers", "select.isolateLayers", explicit);
+        play(&mut s);
+        assert_eq!(s.active().unwrap().isolated_layers, ids);
+        play(&mut s);
+        assert!(s.active().unwrap().isolated_layers.is_empty());
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+}
+
+fn active_text(s: &Session) -> &photocraft_doc::TextLayer {
+    let st = s.active().unwrap();
+    let LayerContent::Text(text) = &st.doc.layer(st.active_layer.unwrap()).unwrap().content else { panic!("expected Type") };
+    text
+}
+
+#[test]
+fn type_default_events_save_then_restore_changed_styles() {
+    for explicit in [false, true] {
+        let mut s = Session::new();
+        s.execute("file.new", json!({"width": 32, "height": 32})).unwrap();
+        s.execute("type.create", json!({"text": "Hi", "size": 14})).unwrap();
+        assert!(s.type_defaults.is_none());
+        load_targeted(&mut s, "textSaveDefaultTypeStyles", "type.saveDefaultTypeStyles", explicit);
+        play(&mut s);
+        assert_eq!(s.type_defaults.as_ref().unwrap().0.size_pt, 14.0);
+        s.execute("type.setStyle", json!({"size": 28})).unwrap();
+        assert_eq!(active_text(&s).char_runs()[0].style.size_pt, 28.0);
+        let before = s.active().unwrap().doc.clone();
+        load_targeted(&mut s, "textLoadDefaultTypeStyles", "type.loadDefaultTypeStyles", explicit);
+        play(&mut s);
+        assert_eq!(active_text(&s).char_runs()[0].style.size_pt, 14.0);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+#[test]
+fn measurement_event_records_actual_selected_area() {
+    for explicit in [false, true] {
+        let mut s = Session::new();
+        s.execute("file.new", json!({"width": 4, "height": 4, "background": "white"})).unwrap();
+        s.execute("select.rect", json!({"x": 0, "y": 0, "width": 2, "height": 2})).unwrap();
+        let before = s.active().unwrap().doc.clone();
+        load_targeted(&mut s, "recordMeasurements", "image.analysis.recordMeasurements", explicit);
+        play(&mut s);
+        assert_eq!(s.analysis.log.len(), 1);
+        assert_eq!(s.analysis.log[0].values["source"], "Selection");
+        assert_eq!(s.analysis.log[0].values["area"].as_f64(), Some(4.0));
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
 #[test]
 fn link_descriptor_headers_normalize_without_changing_meaningful_keys() {
     for event in ["linkSelectedLayers", "unlinkSelectedLayers"] {
diff --git a/docs/atn.md b/docs/atn.md
index 727a5c30c6..2c1e631bec 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -16,6 +16,34 @@ saved as either Photoshop event. Explicit layer lists and extra parameters also
 cannot be saved as these events. Unsupported targets or extra descriptor keys
 are kept as Photoshop steps for lossless saving, rather than partially replayed.
 
+## Other events without settings
+
+| Photoshop event | PhotoCraft command |
+| --- | --- |
+| `reverse` | `layer.arrange.reverse` |
+| `selectLinkedLayers` | `layer.selectLinkedLayers` |
+| `disableLayerStyle` | `layer.layerStyle.clear` |
+| `placedLayerMakeCopy` | `layer.smartObjects.newSmartObjectViaCopy` |
+| `placedLayerConvertToLayers` | `layer.smartObjects.convertToLayers` |
+| `placedLayerConvertToEmbedded` | `layer.smartObjects.convertToEmbedded` |
+| `placedLayerUpdateAllModified` | `layer.smartObjects.updateAllModifiedContent` |
+| `rasterizeAll` | `layer.rasterize.allLayers` |
+| `addBlankVideoLayer` | `layer.videoLayers.newBlankVideoLayer` |
+| `isolateLayers` | `select.isolateLayers` |
+| `textLoadDefaultTypeStyles` | `type.loadDefaultTypeStyles` |
+| `textSaveDefaultTypeStyles` | `type.saveDefaultTypeStyles` |
+| `recordMeasurements` | `image.analysis.recordMeasurements` |
+
+These events and Link/Unlink accept either an empty descriptor or an explicit
+current-layer target. Save retains which form was imported. Other targets or
+extra settings stay complete Photoshop steps; native options with no recorded
+representation are refused on export.
+
+Playback uses each native command's normal preconditions and current state.
+Isolate Layers toggles the panel view. Type defaults are saved in the current
+session. Record Measurements uses the current selection/ruler/count and data
+point configuration.
+
 ## Smart Object file operations
 
 | Photoshop event | Meaningful descriptor keys | PhotoCraft command |

From 1130c8a66c6fa4db591b927354e6b2a258bc69fe Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 13:53:09 -0800
Subject: [PATCH 018/109] feat(engine): map Type to Shape and radius-only Shape
 Blur ATN

---
 crates/engine/src/cmd/atn_cmds/events.rs     |  24 +++
 crates/engine/src/cmd/atn_cmds/steps_make.rs |  10 ++
 crates/engine/src/cmd/atn_cmds/tests.rs      |   3 +
 crates/engine/tests/it/atn_newer_events.rs   | 153 ++++++++++++++++++-
 docs/atn.md                                  |  17 +++
 5 files changed, 205 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index cca7d2d69c..55b0e2966b 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -213,6 +213,28 @@ fn target_only_to(_: &str, p: &Value) -> Option<Descriptor> {
     target_descriptor(p)
 }
 
+const SHAPE_BLUR: &[F] = &[F("Rds ", "radius", Kind::Px)];
+
+fn shape_blur_from(d: &Descriptor) -> Mapped {
+    let unsupported = Mapped::Unsupported { harmless: false };
+    let Some(p) = fields_from(d, SHAPE_BLUR) else { return unsupported };
+    let p = Value::Object(p);
+    if shape_blur_to("filter.blur.shapeBlur", &p).is_some_and(|expected| d.items == expected.items) { step("filter.blur.shapeBlur", p) } else { unsupported }
+}
+
+fn shape_blur_to(_: &str, p: &Value) -> Option<Descriptor> {
+    if !params(p, &["radius"]) {
+        return None;
+    }
+    if let Some(radius) = p.get("radius") {
+        let radius = radius.as_f64()?;
+        if !radius.is_finite() || !(5.0..=1000.0).contains(&radius) {
+            return None;
+        }
+    }
+    fields_to(p, SHAPE_BLUR, desc("null"))
+}
+
 // Recorded Link and Unlink need explicit state: replaying the UI toggle can
 // perform the opposite operation. Target matching follows #10628's adapter.
 fn link_from(d: &Descriptor, linked: bool) -> Mapped {
@@ -310,6 +332,7 @@ pub(super) const EVENTS: &[Event] = &[
     ev!("MtnB", "motionBlur", "Motion Blur", "filter.blur.motionBlur", &[F("Angl", "angle", Kind::Ang), F("Dstn", "distance", Kind::Px)]),
     ev!("", "boxblur", "Box Blur", "filter.blur.boxBlur", &[F("Rds ", "radius", Kind::Px)]),
     ev!("", "surfaceBlur", "Surface Blur", "filter.blur.surfaceBlur", &[F("Rds ", "radius", Kind::Px), F("Thsh", "threshold", Kind::Long)]),
+    Event { code: "", name: "shapeBlur", label: "Shape Blur", ids: &["filter.blur.shapeBlur"], from: shape_blur_from, to: shape_blur_to },
     ev!(
         "SmrB",
         "smartBlur",
@@ -467,6 +490,7 @@ pub(super) const EVENTS: &[Event] = &[
         name: "make",
         label: "Make",
         ids: &[
+            "type.convertToShape",
             "layer.new.layer",
             "layer.new.group",
             "layer.groupLayers",
diff --git a/crates/engine/src/cmd/atn_cmds/steps_make.rs b/crates/engine/src/cmd/atn_cmds/steps_make.rs
index 2fce72c36d..098bd6ab9a 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_make.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_make.rs
@@ -139,7 +139,14 @@ fn new_document_from_descriptor(d: &Descriptor) -> Option<Mapped> {
 /// New Snapshot's From: the full document, the layers merged, or the current layer.
 const SNAPSHOT_FROM: &[(&str, &str)] = &[("FllD", "fullDocument"), ("MrgL", "mergedLayers"), ("CrnL", "currentLayer")];
 
+fn type_shape_descriptor() -> Descriptor {
+    desc("null").with("null", class_ref("contentLayer")).with("Usng", target_ref("textLayer"))
+}
+
 pub(super) fn make_from(d: &Descriptor) -> Mapped {
+    if d.items == type_shape_descriptor().items {
+        return none("type.convertToShape");
+    }
     if let Some(mapped) = duplicate_layer_from_descriptor(d) {
         return mapped;
     }
@@ -224,6 +231,9 @@ pub(super) fn make_from(d: &Descriptor) -> Mapped {
 }
 
 pub(super) fn make_to(id: &str, p: &Value) -> Option<Descriptor> {
+    if id == "type.convertToShape" {
+        return p.as_object().filter(|p| p.is_empty()).map(|_| type_shape_descriptor());
+    }
     let with_name = |cls: &str| {
         let mut u = desc(cls);
         if let Some(n) = jstr(p, "name") {
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 965399241c..757df349a0 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -546,6 +546,9 @@ fn every_mapped_command_exports_and_imports_back() {
         ("layer.duplicate", json!({"layer": "Shadow", "document": "new", "documentName": "Doc"})),
         ("image.duplicate", json!({"mergedOnly": true})),
         ("layer.new.layer", json!({"name": "Ink", "opacity": 0.5, "mode": "Multiply"})),
+        ("type.convertToShape", json!({})),
+        ("filter.blur.shapeBlur", json!({})),
+        ("filter.blur.shapeBlur", json!({"radius": 10})),
         ("layer.new.group", json!({"name": "G"})),
         ("layer.groupLayers", json!({})),
         ("layer.linkLayers", json!({"linked": true})),
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 70db016186..41f5ed7525 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -36,10 +36,14 @@ fn target() -> D {
 }
 
 fn target_class(class_id: &str) -> D {
+    ordinal_target(class_id, "Trgt")
+}
+
+fn ordinal_target(class_id: &str, ordinal: &str) -> D {
     D::Reference(vec![ReferenceItem::Enumerated {
         class: Class { name: UnicodeString::new_nul(""), class_id: Id::new(class_id) },
         type_id: Id::new("Ordn"),
-        value: Id::new("Trgt"),
+        value: Id::new(ordinal),
     }])
 }
 
@@ -49,7 +53,14 @@ fn file(event: &str, descriptor: Descriptor) -> Vec<u8> {
         expanded: false,
         actions: vec![AtnAction {
             name: UnicodeString::new_nul("A"),
-            items: vec![AtnItem { event: AtnEvent::name(event), descriptor: Some(descriptor), ..Default::default() }],
+            items: vec![AtnItem {
+                event: match event.as_bytes() {
+                    [a, b, c, d] => AtnEvent::Code([*a, *b, *c, *d]),
+                    _ => AtnEvent::name(event),
+                },
+                descriptor: Some(descriptor),
+                ..Default::default()
+            }],
             ..Default::default()
         }],
         warnings: vec![],
@@ -67,6 +78,13 @@ fn play(s: &mut Session) {
     assert_eq!(report["ran"], 1, "{report}");
 }
 
+fn saved_item(s: &mut Session) -> AtnItem {
+    let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+    assert_eq!(saved["skipped"], json!([]));
+    let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+    atn::parse(&bytes).unwrap().actions[0].items[0].clone()
+}
+
 #[test]
 fn explicit_links_are_idempotent_and_omitted_state_still_toggles() {
     let mut s = fixture(&[None, None], &[0, 1]);
@@ -459,6 +477,137 @@ fn measurement_event_records_actual_selected_area() {
     }
 }
 
+fn class_reference(class_id: &str) -> D {
+    D::Reference(vec![ReferenceItem::Class(Class { name: UnicodeString::new_nul(""), class_id: Id::new(class_id) })])
+}
+
+fn make_type_descriptor() -> Descriptor {
+    Descriptor::new("Mk  ").with("null", class_reference("contentLayer")).with("Usng", target_class("textLayer"))
+}
+
+#[test]
+fn make_type_shape_roundtrips_and_converts_actual_glyphs_with_undo() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 128, "height": 80, "background": "white"})).unwrap();
+    let id = LayerId(s.execute("type.create", json!({"text": "oil", "size": 24, "x": 8, "y": 48})).unwrap()["layer"].as_u64().unwrap());
+    Arc::make_mut(&mut s.active_mut().unwrap().doc).layer_mut(id).unwrap().psd_blocks.push((*b"TySh", Arc::new(vec![1, 2, 3])));
+    let before = s.active().unwrap().doc.clone();
+    assert_eq!(load(&mut s, &file("Mk  ", make_type_descriptor()))["unsupported"], json!([]));
+    assert_eq!(s.actions.list[0].steps, [("type.convertToShape".into(), json!({}))]);
+    let saved = saved_item(&mut s);
+    assert_eq!(saved.event, AtnEvent::Code(*b"Mk  "));
+    let mut canonical = make_type_descriptor();
+    canonical.class_id = Id::new("null");
+    assert_eq!(saved.descriptor, Some(canonical.clone()));
+    assert_eq!(load(&mut s, &file("Mk  ", canonical))["unsupported"], json!([]));
+    play(&mut s);
+    let layer = s.active().unwrap().doc.layer(id).unwrap();
+    let LayerContent::Shape(shape) = &layer.content else { panic!("Type was not converted to Shape") };
+    assert!(!shape.path.subpaths.is_empty());
+    assert!(!layer.psd_blocks.iter().any(|(key, _)| key == b"TySh"));
+    assert!(s.undo());
+    assert_eq!(s.active().unwrap().doc, before);
+}
+
+#[test]
+fn make_type_shape_keeps_wrong_references_and_preserves_fill_mappings() {
+    for descriptor in [
+        Descriptor::new("null").with("null", class_reference("contentLayer")),
+        Descriptor::new("null").with("null", class_reference("contentLayer")).with("Usng", target_class("Lyr ")),
+        Descriptor::new("null").with("null", class_reference("contentLayer")).with("Usng", ordinal_target("textLayer", "Frnt")),
+        make_type_descriptor().with("extra", D::Boolean(true)),
+        make_type_descriptor().with("Usng", target_class("textLayer")),
+    ] {
+        let mut s = Session::new();
+        assert_eq!(load(&mut s, &file("Mk  ", descriptor.clone()))["unsupported"].as_array().unwrap().len(), 1);
+        assert_eq!(saved_item(&mut s).descriptor, Some(descriptor));
+    }
+    for (id, p) in [("layer.newFillLayer.solidColor", json!({"color": "#ff0000"})), ("layer.newFillLayer.pattern", json!({"pattern": "Grid"}))] {
+        let action = Action::new("A", vec![(id.into(), p)]);
+        let (bytes, skipped) = atn_cmds::export("Links", &[&action], &[], false).unwrap();
+        assert!(skipped.is_empty());
+        let mut s = Session::new();
+        assert_eq!(load(&mut s, &bytes)["unsupported"], json!([]));
+        assert_eq!(s.actions.list[0].steps[0].0, id);
+    }
+    let action = Action::new("A", vec![("type.convertToShape".into(), json!({"layer": 1}))]);
+    assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+}
+
+fn radius_descriptor(radius: f64) -> Descriptor {
+    Descriptor::new("shapeBlur").with("Rds ", D::UnitFloat { unit: *b"#Pxl", value: radius })
+}
+
+fn impulse_fixture() -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 9, "height": 9, "background": "transparent"})).unwrap();
+    s.edit("impulse fixture", |doc, active| {
+        doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().fill_rect(photocraft_doc::Rect::new(4, 4, 5, 5), &[1.0, 1.0, 1.0, 1.0]);
+        Ok(())
+    })
+    .unwrap();
+    s
+}
+
+#[test]
+fn radius_only_shape_blur_roundtrips_and_changes_pixels_including_default() {
+    for radius in [None, Some(5.0)] {
+        let mut s = impulse_fixture();
+        let d = radius.map_or_else(|| Descriptor::new("shapeBlur"), radius_descriptor);
+        assert_eq!(load(&mut s, &file("shapeBlur", d.clone()))["unsupported"], json!([]));
+        let saved = saved_item(&mut s);
+        assert_eq!(saved.event, AtnEvent::name("shapeBlur"));
+        let mut canonical = d;
+        canonical.class_id = Id::new("null");
+        assert_eq!(saved.descriptor, Some(canonical.clone()));
+        assert_eq!(load(&mut s, &file("shapeBlur", canonical))["unsupported"], json!([]));
+        let before = s.active().unwrap().doc.clone();
+        let pixels = photocraft_compose::flatten(&before).px;
+        play(&mut s);
+        let blurred = photocraft_compose::flatten(&s.active().unwrap().doc).px;
+        assert_ne!(blurred, pixels);
+        let mut direct = impulse_fixture();
+        direct.execute("filter.blur.shapeBlur", json!({"radius": radius.unwrap_or(10.0)})).unwrap();
+        assert_eq!(blurred, photocraft_compose::flatten(&direct.active().unwrap().doc).px);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+#[test]
+fn shape_blur_radius_boundaries_keep_their_value_without_running_large_kernels() {
+    for radius in [5.0, 10.0, 1000.0] {
+        let mut s = Session::new();
+        let mut canonical = radius_descriptor(radius);
+        assert_eq!(load(&mut s, &file("shapeBlur", canonical.clone()))["unsupported"], json!([]));
+        assert_eq!(s.actions.list[0].steps[0].1["radius"].as_f64(), Some(radius));
+        canonical.class_id = Id::new("null");
+        assert_eq!(saved_item(&mut s).descriptor, Some(canonical));
+    }
+}
+
+#[test]
+fn shape_blur_keeps_custom_assets_and_invalid_radius_forms_whole() {
+    let custom = Descriptor::new("customShape").with("Nm  ", D::Text(UnicodeString::new_nul("Star"))).with("Idnt", D::Text(UnicodeString::new_nul("asset-id")));
+    for descriptor in [
+        radius_descriptor(4.0),
+        radius_descriptor(1001.0),
+        radius_descriptor(f64::NAN),
+        radius_descriptor(f64::INFINITY),
+        Descriptor::new("shapeBlur").with("Rds ", D::UnitFloat { unit: *b"#Prc", value: 10.0 }),
+        radius_descriptor(10.0).with("customShape", D::Descriptor(custom)).with("keyOriginType", D::Integer(9)),
+        radius_descriptor(10.0).with("extra", D::Boolean(true)),
+    ] {
+        let mut s = Session::new();
+        assert_eq!(load(&mut s, &file("shapeBlur", descriptor.clone()))["unsupported"].as_array().unwrap().len(), 1);
+        assert_eq!(saved_item(&mut s).descriptor.unwrap().to_bytes(), descriptor.to_bytes());
+    }
+    for p in [json!({"radius": 0}), json!({"radius": 1001}), json!({"radius": null}), json!({"radius": 10, "shape": "circle"}), json!({"target": "mask"})] {
+        let action = Action::new("A", vec![("filter.blur.shapeBlur".into(), p)]);
+        assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+    }
+}
+
 #[test]
 fn link_descriptor_headers_normalize_without_changing_meaningful_keys() {
     for event in ["linkSelectedLayers", "unlinkSelectedLayers"] {
diff --git a/docs/atn.md b/docs/atn.md
index 2c1e631bec..98a94434a5 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -44,6 +44,23 @@ Isolate Layers toggles the panel view. Type defaults are saved in the current
 session. Record Measurements uses the current selection/ruler/count and data
 point configuration.
 
+## Type to Shape and radius-only Shape Blur
+
+| Photoshop form | PhotoCraft command |
+| --- | --- |
+| Make `contentLayer`, `Usng` a `textLayer` / `Ordn.Trgt` reference | `type.convertToShape` |
+| `shapeBlur`, optional `Rds ` in pixels, 5–1000 | `filter.blur.shapeBlur` |
+
+Convert Type to Shape retains the Make event and its two references; it does not
+export a separate `convertToShape` event. Other Make forms, including Solid Color
+and Pattern fill layers, retain their existing mappings.
+
+Shape Blur maps the issue's radius-only form through the existing filter. An
+omitted radius uses the native factory value of 10. Later dialog forms containing
+`customShape` or `keyOriginType` stay complete kept steps. Native explicit shape
+choices cannot be exported into a radius-only descriptor. No custom shape asset
+lookup or new blur kernel is supplied by this mapping.
+
 ## Smart Object file operations
 
 | Photoshop event | Meaningful descriptor keys | PhotoCraft command |

From 2d155016599f1a961d1679b6dd3f21706da0c0c2 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 14:02:51 -0800
Subject: [PATCH 019/109] Support recorded direct Gradient Map and Lab-range
 Replace Color

---
 crates/engine/src/cmd/adjust_cmds.rs          |   7 +-
 .../cmd/adjust_cmds/replace_color_range.rs    | 113 +++++
 crates/engine/src/cmd/atn_cmds.rs             |   1 +
 crates/engine/src/cmd/atn_cmds/adjustments.rs |  30 +-
 crates/engine/src/cmd/atn_cmds/events.rs      |  10 +-
 .../cmd/atn_cmds/steps_direct_adjustments.rs  | 182 +++++++
 crates/engine/src/cmd/atn_cmds/tests.rs       |   2 +
 .../engine/tests/it/atn_direct_adjustments.rs | 476 ++++++++++++++++++
 crates/engine/tests/it/main.rs                |   1 +
 9 files changed, 810 insertions(+), 12 deletions(-)
 create mode 100644 crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
 create mode 100644 crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
 create mode 100644 crates/engine/tests/it/atn_direct_adjustments.rs

diff --git a/crates/engine/src/cmd/adjust_cmds.rs b/crates/engine/src/cmd/adjust_cmds.rs
index 39ab43c7a6..cabad771b8 100644
--- a/crates/engine/src/cmd/adjust_cmds.rs
+++ b/crates/engine/src/cmd/adjust_cmds.rs
@@ -18,6 +18,8 @@ use serde_json::{Value, json};
 use crate::commands::CommandSpec;
 use crate::{EngineError, Result, Session};
 
+mod replace_color_range;
+
 /// Built-in Color Lookup looks `(id, label)`.
 pub use photocraft_cms::lutfile::BUILTIN as LOOKS;
 
@@ -402,6 +404,9 @@ fn shadows_highlights_params(p: &Value) -> ShadowsHighlights {
 }
 
 fn replace_color(s: &mut Session, p: &Value) -> Result<Value> {
+    if let Some(result) = replace_color_range::apply(s, p)? {
+        return Ok(result);
+    }
     const CMD: &str = "image.adjustments.replaceColor";
     let c = crate::commands::color_param(CMD, p, "color", s.tools.foreground)?;
     let fuzz = num(p, "fuzziness", 40.0).clamp(0.0, 200.0);
@@ -562,7 +567,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "image.adjustments.replaceColor",
             "Replace Color…",
             ["Image", "Adjustments"],
-            r##"{"localized":bool=false,"color":color,"fuzziness":0..200=40,"range":0..100=100,"hue":-180..180=0,"saturation":-100..100=0,"lightness":-100..100=0,"points":[[x,y],…]?} (color: "#rrggbb", default the foreground colour; Localized Color Clusters: "points" where the colour was picked, "range" % of the longer side)"##,
+            r##"{"localized":bool=false,"color":color,"fuzziness":0..200=40,"range":0..100=100,"hue":-180..180=0,"saturation":-100..100=0,"lightness":-100..100=0,"points":[[x,y],…]?,"labMinimum":[L,a,b]?,"labMaximum":[L,a,b]?} (Lab bounds: a finite ordered D50 box, mutually exclusive with color/points/localized/range; composite pixel-layer target only. Otherwise color defaults to the foreground; localized points use range % of the longer side.)"##,
             has_pixels,
             replace_color
         ),
diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
new file mode 100644
index 0000000000..058f7e8d4e
--- /dev/null
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -0,0 +1,113 @@
+//! Recorded Replace Color samples are a Lab box, not a single RGB colour.
+use photocraft_algo::{selection, tone};
+use photocraft_cms::{Builtin, TransformOptions};
+use photocraft_doc::SampleType;
+use serde_json::Value;
+
+use super::{bad, num};
+use crate::{EngineError, Result, Session};
+
+const CMD: &str = "image.adjustments.replaceColor";
+
+fn bound(p: &Value, key: &str) -> Result<[f64; 3]> {
+    let values = p.get(key).and_then(Value::as_array).filter(|a| a.len() == 3).ok_or_else(|| bad(CMD, format!("`{key}` must be three finite Lab numbers")))?;
+    let mut result = [0.0; 3];
+    for (out, value) in result.iter_mut().zip(values) {
+        let n = value.as_f64().filter(|n| n.is_finite() && (*n as f32).is_finite()).ok_or_else(|| bad(CMD, format!("invalid `{key}` Lab number")))?;
+        *out = n;
+    }
+    Ok(result)
+}
+
+/// Apply explicit recorded bounds; `None` leaves the legacy RGB/sample path alone.
+/// Matching converts original surface channels through their document profile,
+/// before the existing RGBA tone shift can clip or change their colour space.
+pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
+    if p.get("labMinimum").is_none() && p.get("labMaximum").is_none() {
+        return Ok(None);
+    }
+    if ["color", "colors", "points", "subtractPoints", "order", "localized", "range", "channel", "targetChannel"].iter().any(|key| p.get(*key).is_some()) {
+        return Err(bad(CMD, "Lab bounds cannot be combined with RGB samples, localized settings or channel targets"));
+    }
+    if p.get("target").is_some_and(|t| t.as_str() != Some("pixels")) || crate::channel_cmds::edits_channel(s) || crate::color_channels::target(s, p)?.is_some()
+    {
+        return Err(bad(CMD, "Lab bounds require the composite pixel-layer target"));
+    }
+    let (lo, hi) = (bound(p, "labMinimum")?, bound(p, "labMaximum")?);
+    if lo.iter().zip(hi).any(|(lo, hi)| *lo > hi) {
+        return Err(bad(CMD, "Lab minimum must not exceed maximum"));
+    }
+    let mut range = selection::LabRange { lo: lo.map(|v| v as f32), hi: hi.map(|v| v as f32) };
+    // Validate supplied shifts before the edit rather than silently defaulting.
+    for key in ["fuzziness", "hue", "saturation", "lightness"] {
+        if p.get(key).is_some_and(|v| !v.as_f64().is_some_and(f64::is_finite)) {
+            return Err(bad(CMD, format!("`{key}` must be a finite number")));
+        }
+    }
+    let fuzz = num(p, "fuzziness", 40.0).clamp(0.0, 200.0);
+    let (h, sat, l) = (num(p, "hue", 0.0).clamp(-180.0, 180.0), num(p, "saturation", 0.0).clamp(-100.0, 100.0), num(p, "lightness", 0.0).clamp(-100.0, 100.0));
+    let id = crate::commands::layer_param(s, p)?;
+    let st = s.active().ok_or(EngineError::NoDocument)?;
+    super::super::enabled::check_pixels_unlocked(&st.doc, id)?;
+    let surface = st.doc.layer(id).and_then(|l| l.surface()).ok_or_else(|| bad(CMD, "Lab bounds require a pixel layer"))?;
+    let format = surface.format();
+    if format.mode != st.doc.mode {
+        return Err(bad(CMD, "pixel layout does not match the document profile"));
+    }
+    let transform = photocraft_cms::cached(&crate::color_cmds::document_profile(&st.doc), Builtin::LabD50.profile(), TransformOptions::default())
+        .map_err(|e| bad(CMD, format!("Lab colour transform: {e}")))?;
+    if transform.inputs() != format.mode.color_channels() || transform.outputs() != 3 || format.channels() != transform.inputs() + usize::from(format.alpha) {
+        return Err(bad(CMD, "unsupported Lab colour-transform layout"));
+    }
+    let grid = format.sample == SampleType::U8;
+    if grid {
+        range.lo = selection::quantize_lab8(range.lo);
+        range.hi = selection::quantize_lab8(range.hi);
+    }
+    if h == 0.0 && sat == 0.0 && l == 0.0 {
+        // Validation still runs, but a zero shift must not re-separate native inks.
+        return Ok(Some(Value::Null));
+    }
+    s.edit("Replace Color", |doc, _| {
+        let selected = doc.selection.clone();
+        let surface = crate::commands::paint_surface(doc, id, &Value::Null)?;
+        let rect = surface.content_bounds();
+        if rect.is_empty() {
+            return Ok(Value::Null);
+        }
+        let raw = surface.read_region(rect);
+        let mut lab = vec![[0.0, 0.0, 0.0, 1.0]; raw.len() / format.channels()];
+        transform.convert_f32(&raw, format.channels(), lab.as_flattened_mut(), 4, true);
+        for p in &mut lab {
+            let value = [p[0] * 100.0, p[1] * 255.0 - 128.0, p[2] * 255.0 - 128.0];
+            let [l, a, b] = if grid { selection::quantize_lab8(value) } else { value };
+            *p = [l, a, b, p[3]];
+        }
+        let mask = selection::color_range_lab(&lab, rect.width() as usize, &range, fuzz, grid, None);
+        let mut rgba = raw.chunks_exact(format.channels()).map(|p| photocraft_raster::to_rgba(&format, p)).collect::<Vec<_>>();
+        let original_rgba = rgba.clone();
+        tone::replace_color_masked(&mut rgba, &mask, h, sat, l);
+        let mut output = crate::pixels::mix_through_selection(&format, rect, &original_rgba, &rgba, selected.as_ref());
+        // Unmatched native Lab/CMYK values must not take an incidental RGB roundtrip.
+        let width = rect.width() as usize;
+        let row_len = width * format.channels();
+        let mut selection_row = vec![1.0; width];
+        for (y, ((out, original), mask)) in output.chunks_exact_mut(row_len).zip(raw.chunks_exact(row_len)).zip(mask.chunks_exact(width)).enumerate() {
+            if let Some(selected) = selected.as_ref() {
+                selected.sample_row_strided(rect.y0.saturating_add(y as i32), rect.x0, 1, 0, &mut selection_row);
+            }
+            for (x, (((out, original), coverage), selected)) in
+                out.chunks_exact_mut(format.channels()).zip(original.chunks_exact(format.channels())).zip(mask).zip(&selection_row).enumerate()
+            {
+                let index = y * width + x;
+                let unchanged = rgba.get(index).zip(original_rgba.get(index)).is_some_and(|(a, b)| a == b);
+                if *coverage <= 0.0 || *selected <= 0.0 || unchanged {
+                    out.copy_from_slice(original);
+                }
+            }
+        }
+        surface.write_region(rect, &output);
+        Ok(Value::Null)
+    })
+    .map(Some)
+}
diff --git a/crates/engine/src/cmd/atn_cmds.rs b/crates/engine/src/cmd/atn_cmds.rs
index 42a4722479..bdcbe35548 100644
--- a/crates/engine/src/cmd/atn_cmds.rs
+++ b/crates/engine/src/cmd/atn_cmds.rs
@@ -32,6 +32,7 @@ mod descriptors;
 mod events;
 mod fields;
 mod files;
+mod steps_direct_adjustments;
 mod steps_doc;
 mod steps_image;
 mod steps_layer;
diff --git a/crates/engine/src/cmd/atn_cmds/adjustments.rs b/crates/engine/src/cmd/atn_cmds/adjustments.rs
index 5da802b800..80339db65c 100644
--- a/crates/engine/src/cmd/atn_cmds/adjustments.rs
+++ b/crates/engine/src/cmd/atn_cmds/adjustments.rs
@@ -344,6 +344,11 @@ fn gradient_map_from(d: &Descriptor) -> Option<Value> {
 }
 
 fn gradient_map_to(p: &Value) -> Option<Descriptor> {
+    // A recorded GrMp has its own strict converter. Never fall back to the older
+    // event if its origin/settings were changed into an unrepresentable form.
+    if p.get(super::steps_direct_adjustments::GRADIENT_ORIGIN).is_some() {
+        return None;
+    }
     let stops: Option<Vec<D>> = p
         .get("stops")?
         .as_array()?
@@ -359,16 +364,7 @@ fn gradient_map_to(p: &Value) -> Option<Descriptor> {
             ))
         })
         .collect();
-    let transparency = D::List(vec![
-        D::Descriptor(desc("TrnS").with("Opct", pct(100.0)).with("Lctn", long(0.0)).with("Mdpn", long(50.0))),
-        D::Descriptor(desc("TrnS").with("Opct", pct(100.0)).with("Lctn", long(4096.0)).with("Mdpn", long(50.0))),
-    ]);
-    let grad = desc("Grdn")
-        .with("Nm  ", text("Custom"))
-        .with("GrdF", enm("GrdF", "CstS"))
-        .with("Intr", D::Double(4096.0))
-        .with("Clrs", D::List(stops?))
-        .with("Trns", transparency);
+    let grad = gradient_descriptor(stops?, "Custom");
     let mut d = desc("GdMp").with("Grad", D::Descriptor(grad));
     if let Some(r) = jbool(p, "reverse") {
         d = d.with("Rvrs", D::Boolean(r));
@@ -379,6 +375,20 @@ fn gradient_map_to(p: &Value) -> Option<Descriptor> {
     Some(d)
 }
 
+/// The classic, opaque gradient shared by direct and adjustment-layer mappings.
+pub(super) fn gradient_descriptor(stops: Vec<D>, name: &str) -> Descriptor {
+    let transparency = D::List(vec![
+        D::Descriptor(desc("TrnS").with("Opct", pct(100.0)).with("Lctn", long(0.0)).with("Mdpn", long(50.0))),
+        D::Descriptor(desc("TrnS").with("Opct", pct(100.0)).with("Lctn", long(4096.0)).with("Mdpn", long(50.0))),
+    ]);
+    desc("Grdn")
+        .with("Nm  ", text(name))
+        .with("GrdF", enm("GrdF", "CstS"))
+        .with("Intr", D::Double(4096.0))
+        .with("Clrs", D::List(stops))
+        .with("Trns", transparency)
+}
+
 /// An adjustment: its Photoshop class (usually also the direct event's code; Black & White and
 /// Photo Filter run by name), the command suffix (`image.adjustments.<suffix>`, `layer.newAdjustmentLayer.<suffix>`), and
 /// the converters between the adjustment descriptor and the command params.
diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 5723c93c59..30c0834e9e 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -2,6 +2,7 @@ const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
 use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, ref_class};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
+use super::steps_direct_adjustments::{gradient_from, gradient_to, replace_from, replace_to};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
     crop_from, crop_to, export_from, export_to, image_size_from, image_size_to, merge_visible_from, merge_visible_to, open_from, open_to, paste_from, paste_to,
@@ -281,7 +282,9 @@ pub(super) const EVENTS: &[Event] = &[
     adjustment_event!("", "PhtF", "photoFilter", "Photo Filter"),
     adjustment_event!("", "BanW", "blackAndWhite", "Black & White", "image.adjustments.blackWhite"),
     adjustment_event!("ChnM", "ChnM", "channelMixer", "Channel Mixer"),
+    Event { code: "GrMp", name: "", label: "Gradient Map", ids: &["image.adjustments.gradientMap"], from: gradient_from, to: gradient_to },
     adjustment_event!("GdMp", "GdMp", "gradientMapEvent", "Gradient Map", "image.adjustments.gradientMap"),
+    Event { code: "RplC", name: "replaceColor", label: "Replace Color", ids: &["image.adjustments.replaceColor"], from: replace_from, to: replace_to },
     adjustment_event!("SlcC", "SlcC", "selectiveColor", "Selective Color"),
     ev!("Dstt", "desaturate", "Desaturate", "image.adjustments.desaturate", &[]),
     ev!("Eqlz", "equalize", "Equalize", "image.adjustments.equalize", &[]),
@@ -617,7 +620,12 @@ const LEGACY_CODES: &[(&str, &str)] =
 
 pub(super) fn event_for(item: &AtnEvent) -> Option<&'static Event> {
     let id = item.id();
-    let find = |id: &str| EVENTS.iter().find(|e| (!e.code.is_empty() && e.code.trim_end() == id.trim_end()) || e.name == id);
+    let find = |id: &str| {
+        EVENTS.iter().find(|e| {
+            (!e.code.is_empty() && e.code.trim_end() == id.trim_end() && (!e.name.is_empty() || matches!(item, AtnEvent::Code(_))))
+                || (!e.name.is_empty() && e.name == id)
+        })
+    };
     find(&id).or_else(|| match item {
         AtnEvent::Code(_) => LEGACY_CODES.iter().find(|(code, _)| *code == id).and_then(|(_, name)| find(name)),
         AtnEvent::Name(_) => None,
diff --git a/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs b/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
new file mode 100644
index 0000000000..ace8c22938
--- /dev/null
+++ b/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
@@ -0,0 +1,182 @@
+//! Direct GrMp and RplC forms measured in #10603 (Group E).
+use super::adjustments::gradient_descriptor;
+use super::descriptors::{desc, enm, get_list, get_num, get_obj};
+use super::events::pixel_target;
+use super::fields::{Mapped, step};
+use super::{D, Descriptor, Value, json};
+
+/// Typed source values needed to retain the direct event and fractional RGB on save.
+/// Execution uses ordinary numeric RGB stops, never a stored descriptor.
+pub(super) const GRADIENT_ORIGIN: &str = "__atnGrMp";
+
+fn only_params(p: &Value, allowed: &[&str]) -> bool {
+    p.as_object().is_some_and(|p| p.keys().all(|k| allowed.contains(&k.as_str())))
+}
+
+fn triple(p: &Value) -> Option<[f64; 3]> {
+    let a = p.as_array().filter(|a| a.len() == 3)?;
+    Some([a.first()?.as_f64()?, a.get(1)?.as_f64()?, a.get(2)?.as_f64()?])
+}
+
+/// Import only a descriptor the native stop model and the strict writer retain.
+/// Comparing the reconstructed typed descriptor rejects dropped settings, unknown
+/// keys, duplicates, unsupported units/classes and lossy wire-type conversions.
+pub(super) fn gradient_from(d: &Descriptor) -> Mapped {
+    let mapped = || {
+        let g = get_obj(d, "Grad")?;
+        let D::Text(name) = g.get("Nm  ")? else { return None };
+        let mut stops = Vec::new();
+        let mut colors = Vec::new();
+        for s in get_list(g, "Clrs").filter(|s| (2..=64).contains(&s.len()))? {
+            let D::Descriptor(s) = s else { return None };
+            let c = get_obj(s, "Clr ")?;
+            let rgb = [get_num(c, "Rd  ")?, get_num(c, "Grn ")?, get_num(c, "Bl  ")?];
+            colors.push(rgb);
+            stops.push(json!([get_num(s, "Lctn")? / 4096.0, rgb.map(|v| v / 255.0)]));
+        }
+        let mut p = json!({"stops": stops, GRADIENT_ORIGIN: {"name": name.to_string_lossy(), "colors": colors}});
+        if d.get("gradientsInterpolationMethod").is_none() {
+            // The measured default is classic; retain omission as well as meaning.
+            p[GRADIENT_ORIGIN]["omitInterpolation"] = json!(true);
+        }
+        for (key, param) in [("Rvrs", "reverse"), ("Dthr", "dither")] {
+            if let Some(v) = d.get(key) {
+                let D::Boolean(v) = v else { return None };
+                p[param] = json!(v);
+            }
+        }
+        (gradient_to("", &p)?.eq(d)).then_some(p)
+    };
+    mapped().map_or(Mapped::Unsupported { harmless: false }, |p| step("image.adjustments.gradientMap", p))
+}
+
+/// Write the measured classic form. The exact source RGB values must still agree
+/// with the executed stops, so changing a stop never revives stale source data.
+pub(super) fn gradient_to(_: &str, p: &Value) -> Option<Descriptor> {
+    if !pixel_target(p) || !only_params(p, &["stops", "reverse", "dither", "target", GRADIENT_ORIGIN]) {
+        return None;
+    }
+    let origin = p.get(GRADIENT_ORIGIN)?;
+    if !only_params(origin, &["name", "colors", "omitInterpolation"]) {
+        return None;
+    }
+    let name = origin.get("name")?.as_str()?;
+    let colors = origin.get("colors")?.as_array()?;
+    let stops = p.get("stops")?.as_array().filter(|s| (2..=64).contains(&s.len()) && s.len() == colors.len())?;
+    let mut encoded = Vec::with_capacity(stops.len());
+    let mut previous = -1.0;
+    for (stop, color) in stops.iter().zip(colors) {
+        let a = stop.as_array().filter(|a| a.len() == 2)?;
+        let position = a.first()?.as_f64()?;
+        if !position.is_finite() || !(0.0..=1.0).contains(&position) || position < previous || (position * 4096.0).fract() != 0.0 {
+            return None;
+        }
+        previous = position;
+        let rgb = triple(color)?;
+        if !rgb.iter().all(|v| v.is_finite() && (0.0..=255.0).contains(v)) || triple(a.get(1)?)? != rgb.map(|v| v / 255.0) {
+            return None;
+        }
+        let rgb = desc("RGBC").with("Rd  ", D::Double(rgb[0])).with("Grn ", D::Double(rgb[1])).with("Bl  ", D::Double(rgb[2]));
+        encoded.push(D::Descriptor(
+            desc("Clrt")
+                .with("Clr ", D::Descriptor(rgb))
+                .with("Type", enm("Clry", "UsrS"))
+                .with("Lctn", D::Integer((position * 4096.0) as i32))
+                .with("Mdpn", D::Integer(50)),
+        ));
+    }
+    let mut d = desc("null");
+    let omit = match origin.get("omitInterpolation") {
+        None => false,
+        Some(v) => v.as_bool()?,
+    };
+    if !omit {
+        d = d.with("gradientsInterpolationMethod", enm("gradientInterpolationMethodType", "Gcls"));
+    }
+    d = d.with("Grad", D::Descriptor(gradient_descriptor(encoded, name)));
+    for (param, key) in [("reverse", "Rvrs"), ("dither", "Dthr")] {
+        if let Some(v) = p.get(param) {
+            d = d.with(key, D::Boolean(v.as_bool()?));
+        }
+    }
+    Some(d)
+}
+
+fn lab_bound(p: &Value) -> Option<[f64; 3]> {
+    let values = triple(p)?;
+    values.iter().all(|v| v.is_finite() && (*v as f32).is_finite()).then_some(values)
+}
+
+fn ordered(d: &Descriptor, keys: &[&str]) -> bool {
+    d.items.len() == keys.len() && d.items.iter().zip(keys).all(|((key, _), expected)| key.is(expected))
+}
+
+fn lab_from(v: &D) -> Option<[f64; 3]> {
+    let D::Descriptor(d) = v else { return None };
+    if !d.class_id.is("LbCl") || !d.name.0.is_empty() || !ordered(d, &["Lmnc", "A   ", "B   "]) {
+        return None;
+    }
+    let values = d
+        .items
+        .iter()
+        .map(|(_, v)| match v {
+            D::Double(n) => Some(*n),
+            _ => None,
+        })
+        .collect::<Option<Vec<_>>>()?;
+    lab_bound(&json!(values))
+}
+
+/// RplC records the sampled D50 box directly. RGB conversion would lose both the
+/// box width and out-of-gamut coordinates, so pass its bounds to the native command.
+pub(super) fn replace_from(d: &Descriptor) -> Mapped {
+    let mapped = || {
+        if !d.class_id.is("null") || !d.name.0.is_empty() || !ordered(d, &["Fzns", "Mnm ", "Mxm ", "H   ", "Strt", "Lght", "colorModel"]) {
+            return None;
+        }
+        let (lo, hi) = (lab_from(d.get("Mnm ")?)?, lab_from(d.get("Mxm ")?)?);
+        if lo.iter().zip(hi).any(|(lo, hi)| *lo > hi) || !matches!(d.get("colorModel"), Some(D::Integer(0))) {
+            return None;
+        }
+        let mut p = json!({"labMinimum": lo, "labMaximum": hi});
+        for (key, param, lo, hi) in
+            [("Fzns", "fuzziness", 0, 200), ("H   ", "hue", -180, 180), ("Strt", "saturation", -100, 100), ("Lght", "lightness", -100, 100)]
+        {
+            let D::Integer(n) = d.get(key)? else { return None };
+            p[param] = json!((*n).clamp(lo, hi));
+        }
+        Some(p)
+    };
+    mapped().map_or(Mapped::Unsupported { harmless: false }, |p| step("image.adjustments.replaceColor", p))
+}
+
+/// Emit all measured keys in order. Fractional native shifts have no integer ATN
+/// representation and are refused; an ordinary RGB-sample call is not a Lab box.
+pub(super) fn replace_to(_: &str, p: &Value) -> Option<Descriptor> {
+    if !pixel_target(p) || !only_params(p, &["labMinimum", "labMaximum", "fuzziness", "hue", "saturation", "lightness", "target"]) {
+        return None;
+    }
+    let (lo, hi) = (lab_bound(p.get("labMinimum")?)?, lab_bound(p.get("labMaximum")?)?);
+    if lo.iter().zip(hi).any(|(lo, hi)| *lo > hi) {
+        return None;
+    }
+    let lab = |v: [f64; 3]| D::Descriptor(desc("LbCl").with("Lmnc", D::Double(v[0])).with("A   ", D::Double(v[1])).with("B   ", D::Double(v[2])));
+    let field = |key, default: f64, lo, hi| {
+        let n = match p.get(key) {
+            None => default,
+            Some(v) => v.as_f64()?,
+        };
+        let n = n.is_finite().then_some(n)?.clamp(lo, hi);
+        (n.fract() == 0.0).then_some(D::Integer(n as i32))
+    };
+    Some(
+        desc("null")
+            .with("Fzns", field("fuzziness", 40.0, 0.0, 200.0)?)
+            .with("Mnm ", lab(lo))
+            .with("Mxm ", lab(hi))
+            .with("H   ", field("hue", 0.0, -180.0, 180.0)?)
+            .with("Strt", field("saturation", 0.0, -100.0, 100.0)?)
+            .with("Lght", field("lightness", 0.0, -100.0, 100.0)?)
+            .with("colorModel", D::Integer(0)),
+    )
+}
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index f9e633244c..f9fb795a84 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -615,6 +615,8 @@ fn every_mapped_command_exports_and_imports_back() {
             json!({"path": "C:\\shots\\a.jpg", "format": "jpeg", "interlaced": false, "transparency": false, "embedIcc": true, "progressive": true, "optimized": true, "quality": 80, "matte": "none"}),
         ),
         ("image.adjustments.gradientMap", json!({"stops": [[0, "#000000"], [0.5, "#ff8000"], [1, "#ffffff"]], "reverse": true, "dither": false})),
+        ("image.adjustments.gradientMap", json!({"stops": [[0,[0.5,0,0]],[1,[0,1,0]]], "__atnGrMp":{"name":"Recorded","colors":[[127.5,0,0],[0,255,0]]}})),
+        ("image.adjustments.replaceColor", json!({"labMinimum":[40,30,40],"labMaximum":[60,35,45],"fuzziness":40,"hue":30,"saturation":0,"lightness":0})),
         ("layer.newAdjustmentLayer.gradientMap", json!({"stops": [[0, "#102030"], [1, "#f0e0d0"]], "reverse": false, "dither": true})),
         ("layer.smartObjects.convertToSmartObject", json!({})),
         ("layer.smartObjects.editContents", json!({})),
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
new file mode 100644
index 0000000000..3cefe7ba0a
--- /dev/null
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -0,0 +1,476 @@
+//! Recorded direct Gradient Map and Replace Color forms from #10603 / #10607.
+use photocraft_engine::{Session, atn_cmds};
+use photocraft_psd::{
+    atn::{self, AtnAction, AtnEvent, AtnFile, AtnItem},
+    descriptor::{Descriptor, Id, UnicodeString, Value as D},
+};
+use serde_json::json;
+
+fn enumeration(kind: &str, value: &str) -> D {
+    D::Enumerated { type_id: Id::new(kind), value: Id::new(value) }
+}
+
+fn color(red: f64, green: f64, blue: f64) -> D {
+    D::Descriptor(Descriptor::new("RGBC").with("Rd  ", D::Double(red)).with("Grn ", D::Double(green)).with("Bl  ", D::Double(blue)))
+}
+
+fn gradient() -> Descriptor {
+    let stop = |location, rgb| {
+        D::Descriptor(
+            Descriptor::new("Clrt").with("Clr ", rgb).with("Type", enumeration("Clry", "UsrS")).with("Lctn", D::Integer(location)).with("Mdpn", D::Integer(50)),
+        )
+    };
+    let opacity = |location| {
+        D::Descriptor(
+            Descriptor::new("TrnS").with("Opct", D::UnitFloat { unit: *b"#Prc", value: 100.0 }).with("Lctn", D::Integer(location)).with("Mdpn", D::Integer(50)),
+        )
+    };
+    Descriptor::new("null").with("gradientsInterpolationMethod", enumeration("gradientInterpolationMethodType", "Gcls")).with(
+        "Grad",
+        D::Descriptor(
+            Descriptor::new("Grdn")
+                .with("Nm  ", D::Text(UnicodeString::new_nul("Recorded gradient")))
+                .with("GrdF", enumeration("GrdF", "CstS"))
+                .with("Intr", D::Double(4096.0))
+                .with("Clrs", D::List(vec![stop(0, color(0.0, 0.0, 255.0)), stop(4096, color(255.0, 0.0, 0.0))]))
+                .with("Trns", D::List(vec![opacity(0), opacity(4096)])),
+        ),
+    )
+}
+
+fn replace() -> Descriptor {
+    let lab = || D::Descriptor(Descriptor::new("LbCl").with("Lmnc", D::Double(40.0)).with("A   ", D::Double(30.0)).with("B   ", D::Double(40.0)));
+    Descriptor::new("null")
+        .with("Fzns", D::Integer(40))
+        .with("Mnm ", lab())
+        .with("Mxm ", lab())
+        .with("H   ", D::Integer(30))
+        .with("Strt", D::Integer(0))
+        .with("Lght", D::Integer(0))
+        .with("colorModel", D::Integer(0))
+}
+
+fn bytes(event: [u8; 4], descriptor: Descriptor) -> Vec<u8> {
+    atn::write(&AtnFile {
+        name: UnicodeString::new_nul("Direct adjustments"),
+        expanded: false,
+        actions: vec![AtnAction {
+            name: UnicodeString::new_nul("Recorded"),
+            items: vec![AtnItem { event: AtnEvent::Code(event), descriptor: Some(descriptor), ..Default::default() }],
+            ..Default::default()
+        }],
+        warnings: vec![],
+    })
+    .unwrap()
+}
+
+fn load(event: [u8; 4], descriptor: Descriptor, command: &str) -> Session {
+    let mut s = Session::new();
+    let bytes = bytes(event, descriptor);
+    let report = s.execute("actions.load", json!({"data": photocraft_paint::tile::b64_encode(&bytes)})).unwrap();
+    assert_eq!(report["unsupported"], json!([]), "recorded {} must map to {command}", String::from_utf8_lossy(&event));
+    assert_eq!(s.actions.list[0].steps[0].0, command);
+    s
+}
+
+#[test]
+fn recorded_grmp_imports_as_direct_gradient_map() {
+    let s = load(*b"GrMp", gradient(), "image.adjustments.gradientMap");
+    assert_eq!(s.actions.list[0].steps[0].1["stops"], json!([[0, [0, 0, 1]], [1, [1, 0, 0]]]));
+}
+
+#[test]
+fn recorded_rplc_imports_as_direct_replace_color() {
+    let s = load(*b"RplC", replace(), "image.adjustments.replaceColor");
+    assert_eq!(s.actions.list[0].steps[0].1["hue"], json!(30));
+}
+
+fn saved(s: &Session) -> AtnItem {
+    let refs = s.actions.list.iter().collect::<Vec<_>>();
+    let (bytes, skipped) = atn_cmds::export("Direct adjustments", &refs, &[], false).unwrap();
+    assert!(skipped.is_empty());
+    atn::parse(&bytes).unwrap().actions.remove(0).items.remove(0)
+}
+
+fn object<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Descriptor {
+    match &mut d.items.iter_mut().find(|(k, _)| k.is(key)).unwrap().1 {
+        D::Descriptor(d) => d,
+        _ => panic!("not an object"),
+    }
+}
+
+fn list<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Vec<D> {
+    match &mut d.items.iter_mut().find(|(k, _)| k.is(key)).unwrap().1 {
+        D::List(l) => l,
+        _ => panic!("not a list"),
+    }
+}
+
+fn first_stop(d: &mut Descriptor) -> &mut Descriptor {
+    match &mut list(object(d, "Grad"), "Clrs")[0] {
+        D::Descriptor(d) => d,
+        _ => panic!("not a stop"),
+    }
+}
+
+#[test]
+fn direct_forms_save_exact_descriptors_including_fractional_rgb() {
+    let mut fractional = gradient();
+    object(first_stop(&mut fractional), "Clr ").items[0].1 = D::Double(73.1234567);
+    let mut defaults = gradient();
+    object(first_stop(&mut defaults), "Clr ").items[2].1 = D::Double(0.0);
+    let g = object(&mut defaults, "Grad");
+    let D::Descriptor(stop) = &mut list(g, "Clrs")[1] else { panic!("stop") };
+    object(stop, "Clr ").items[1].1 = D::Double(255.0);
+    object(stop, "Clr ").items[2].1 = D::Double(255.0);
+    let mut implicit_classic = gradient();
+    implicit_classic.items.remove(0);
+    for descriptor in [defaults, gradient(), fractional, implicit_classic] {
+        let s = load(*b"GrMp", descriptor.clone(), "image.adjustments.gradientMap");
+        let item = saved(&s);
+        assert_eq!(item.event, AtnEvent::Code(*b"GrMp"));
+        assert_eq!(item.descriptor, Some(descriptor));
+    }
+    let mut changed = replace();
+    object(&mut changed, "Mnm ").items[0].1 = D::Double(20.125);
+    changed.items[0].1 = D::Integer(130);
+    changed.items[3].1 = D::Integer(-120);
+    changed.items[4].1 = D::Integer(45);
+    changed.items[5].1 = D::Integer(-20);
+    for descriptor in [replace(), changed] {
+        let s = load(*b"RplC", descriptor.clone(), "image.adjustments.replaceColor");
+        assert_eq!(saved(&s).descriptor, Some(descriptor));
+    }
+}
+
+fn fixture(mode: &str, depth: u32) -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width":4,"height":1,"mode":mode,"depth":depth})).unwrap();
+    s.edit("original pixels", |doc, active| {
+        let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+        let format = surface.format();
+        let data = [[0.0, 0.0, 0.0, 1.0], [0.3, 0.8, 0.2, 1.0], [0.7, 0.2, 0.6, 0.4], [1.0, 1.0, 1.0, 1.0]]
+            .into_iter()
+            .flat_map(|p| photocraft_raster::from_rgba(&format, p))
+            .collect::<Vec<_>>();
+        surface.write_region(photocraft_doc::Rect::from_xywh(0, 0, 4, 1), &data);
+        Ok(())
+    })
+    .unwrap();
+    s
+}
+
+fn raw(s: &Session) -> Vec<f32> {
+    let st = s.active().unwrap();
+    st.doc.layer(st.active_layer.unwrap()).unwrap().surface().unwrap().read_region(st.doc.bounds())
+}
+
+fn play(s: &mut Session) {
+    let report = s.execute("actions.play", json!({"action":"Recorded","set":"Direct adjustments"})).unwrap();
+    assert_eq!(report["ran"], 1, "{report}");
+    assert!(report.get("failed").is_none(), "{report}");
+}
+
+#[test]
+fn fractional_gradient_changes_pixels_and_preserves_selection_and_undo() {
+    let mut descriptor = gradient();
+    object(first_stop(&mut descriptor), "Clr ").items[0].1 = D::Double(73.125);
+    for depth in [8, 16, 32] {
+        let imported = atn_cmds::import(&bytes(*b"GrMp", descriptor.clone())).unwrap();
+        assert!(imported.unsupported.is_empty());
+        let mut direct = fixture("rgb", depth);
+        direct.execute("select.rect", json!({"x":0,"y":0,"width":3,"height":1})).unwrap();
+        let original = raw(&direct);
+        direct.execute("image.adjustments.gradientMap", imported.actions[0].steps[0].1.clone()).unwrap();
+        let expected = raw(&direct);
+        assert_ne!(expected, original);
+        assert_eq!(&expected[12..], &original[12..], "outside the selection");
+        let mut replay = fixture("rgb", depth);
+        replay.execute("select.rect", json!({"x":0,"y":0,"width":3,"height":1})).unwrap();
+        replay.actions.list = imported.actions;
+        play(&mut replay);
+        assert_eq!(raw(&replay), expected);
+        assert!(replay.undo());
+        assert_eq!(raw(&replay), original);
+        if depth == 32 {
+            assert!((expected[0] - 73.125 / 255.0).abs() < 1e-6, "fractional color must not be rounded to hex");
+        }
+    }
+}
+
+fn set_lab_pixels(s: &mut Session) {
+    s.edit("known Lab pixels", |doc, active| {
+        let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+        surface.write_region(
+            photocraft_doc::Rect::from_xywh(0, 0, 4, 1),
+            &[
+                0.4,
+                128.0 / 255.0,
+                128.0 / 255.0,
+                1.0,
+                0.5,
+                128.0 / 255.0,
+                128.0 / 255.0,
+                1.0,
+                0.6,
+                128.0 / 255.0,
+                128.0 / 255.0,
+                1.0,
+                0.95,
+                128.0 / 255.0,
+                128.0 / 255.0,
+                1.0,
+            ],
+        );
+        Ok(())
+    })
+    .unwrap();
+}
+
+#[test]
+fn lab_boxes_with_the_same_midpoint_have_different_real_effects() {
+    // Independent mask anchors: at zero fuzziness a neutral Lab50 pixel is
+    // inside both boxes, Lab40/60 only the wide one, and Lab95 is outside both.
+    for depth in [8, 16, 32] {
+        let mut results = Vec::new();
+        for (minimum, maximum) in [(49, 51), (39, 61)] {
+            let mut s = fixture("lab", depth);
+            set_lab_pixels(&mut s);
+            let before = raw(&s);
+            s.execute("image.adjustments.replaceColor", json!({"labMinimum":[minimum,0,0],"labMaximum":[maximum,0,0],"fuzziness":0,"lightness":100})).unwrap();
+            let after = raw(&s);
+            assert!(after[4] > 0.99, "Lab50 must become white: {after:?}");
+            assert!((after[12] - before[12]).abs() < 0.005, "Lab95 stays outside");
+            if minimum == 49 {
+                assert!((after[0] - before[0]).abs() < 0.005);
+            } else {
+                assert!(after[0] > 0.99 && after[8] > 0.99, "wide box includes Lab40/60");
+            }
+            results.push(after);
+            assert!(s.undo());
+            assert_eq!(raw(&s), before);
+        }
+        assert_ne!(results[0], results[1], "collapsing a box to its midpoint is incorrect");
+    }
+}
+
+#[test]
+fn invalid_lab_inputs_are_rejected_before_any_edit() {
+    let mut s = fixture("rgb", 32);
+    for patch in [
+        json!({"labMaximum":null}),
+        json!({"labMinimum":[0,0]}),
+        json!({"labMinimum":[1e100,0,0]}),
+        json!({"labMinimum":[50.0000001,0,0],"labMaximum":[50,0,0]}),
+        json!({"color":"#ff0000"}),
+        json!({"points":[]}),
+        json!({"localized":false}),
+        json!({"target":"mask"}),
+        json!({"hue":"30"}),
+        json!({"layer":999999}),
+    ] {
+        let mut p = json!({"labMinimum":[40,0,0],"labMaximum":[60,0,0],"lightness":100});
+        p.as_object_mut().unwrap().extend(patch.as_object().unwrap().clone());
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        assert!(s.execute("image.adjustments.replaceColor", p.clone()).is_err(), "{p}");
+        assert_eq!(s.active().unwrap().doc, before, "{p}");
+        assert_eq!(s.active().unwrap().history.past_len(), history, "{p}");
+    }
+}
+
+fn kept(event: [u8; 4], d: Descriptor) {
+    let imported = atn_cmds::import(&bytes(event, d.clone())).unwrap();
+    assert_eq!(imported.unsupported.len(), 1, "{d:?}");
+    let mut s = Session::new();
+    s.actions.list = imported.actions;
+    assert_eq!(saved(&s).descriptor, Some(d));
+}
+
+#[test]
+fn unsupported_gradient_settings_and_wire_forms_remain_kept() {
+    let mut midpoint = gradient();
+    first_stop(&mut midpoint).items[3].1 = D::Integer(30);
+    let mut transparency = gradient();
+    let D::Descriptor(opacity) = &mut list(object(&mut transparency, "Grad"), "Trns")[0] else { panic!("opacity") };
+    opacity.items[0].1 = D::UnitFloat { unit: *b"#Prc", value: 50.0 };
+    let mut interpolation = gradient();
+    interpolation.items[0].1 = enumeration("gradientInterpolationMethodType", "Lnr ");
+    let mut order = gradient();
+    list(object(&mut order, "Grad"), "Clrs").reverse();
+    let mut duplicate = gradient();
+    duplicate.items.push(duplicate.items[0].clone());
+    let mut unknown = gradient();
+    unknown.items.push((Id::new("extra"), D::Boolean(true)));
+    for d in [midpoint, transparency, interpolation, order, duplicate, unknown] {
+        kept(*b"GrMp", d);
+    }
+    let mut f = atn::parse(&bytes(*b"GrMp", gradient())).unwrap();
+    f.actions[0].items[0].event = AtnEvent::name("GrMp");
+    assert_eq!(atn_cmds::import(&atn::write(&f).unwrap()).unwrap().unsupported.len(), 1);
+}
+
+#[test]
+fn invalid_replace_descriptors_and_lossy_exports_are_refused() {
+    let mut model = replace();
+    model.items[6].1 = D::Integer(1);
+    let mut inverted = replace();
+    object(&mut inverted, "Mnm ").items[0].1 = D::Double(80.0);
+    let mut missing = replace();
+    missing.items.remove(0);
+    let mut unknown = replace();
+    unknown.items.push((Id::new("extra"), D::Boolean(true)));
+    let mut duplicate = replace();
+    duplicate.items.push(duplicate.items[0].clone());
+    for d in [model, inverted, missing, unknown, duplicate] {
+        kept(*b"RplC", d);
+    }
+    let mut s = load(*b"GrMp", gradient(), "image.adjustments.gradientMap");
+    s.actions.list[0].steps[0].1["stops"][0][1][0] = json!(0.2);
+    assert!(atn_cmds::export("Direct adjustments", &[&s.actions.list[0]], &[], false).is_err(), "stale color metadata must not fall through to GdMp");
+    for p in [json!({"color":"#ff0000"}), json!({"labMinimum":[40,0,0],"labMaximum":[60,0,0],"hue":0.5})] {
+        let a = photocraft_engine::actions_cmds::Action::new("Native", vec![("image.adjustments.replaceColor".into(), p)]);
+        assert!(atn_cmds::export("Direct adjustments", &[&a], &[], false).is_err());
+    }
+}
+
+#[test]
+fn recorded_replace_color_clamps_shifts_and_plays_the_lab_box_at_every_depth() {
+    for depth in [8, 16, 32] {
+        let mut d = replace();
+        for key in ["Mnm ", "Mxm "] {
+            let o = object(&mut d, key);
+            o.items[0].1 = D::Double(if key == "Mnm " { 39.0 } else { 61.0 });
+            o.items[1].1 = D::Double(0.0);
+            o.items[2].1 = D::Double(0.0);
+        }
+        d.items[0].1 = D::Integer(-10);
+        d.items[3].1 = D::Integer(0);
+        d.items[5].1 = D::Integer(250);
+        let imported = atn_cmds::import(&bytes(*b"RplC", d)).unwrap();
+        assert!(imported.unsupported.is_empty());
+        assert_eq!(imported.actions[0].steps[0].1["fuzziness"], 0);
+        assert_eq!(imported.actions[0].steps[0].1["lightness"], 100);
+        let mut s = fixture("lab", depth);
+        set_lab_pixels(&mut s);
+        s.execute("select.rect", json!({"x":0,"y":0,"width":2,"height":1})).unwrap();
+        let before = raw(&s);
+        s.actions.list = imported.actions;
+        play(&mut s);
+        let after = raw(&s);
+        assert!(after[0] > 0.99 && after[4] > 0.99);
+        assert_eq!(&after[8..], &before[8..], "selection must bound the edit");
+        assert!(s.undo());
+        assert_eq!(raw(&s), before);
+        let descriptor = saved(&s).descriptor.unwrap();
+        assert_eq!(descriptor.get("Fzns"), Some(&D::Integer(0)));
+        assert_eq!(descriptor.get("Lght"), Some(&D::Integer(100)));
+    }
+}
+
+#[test]
+fn lab_matching_uses_native_channels_and_the_embedded_rgb_profile() {
+    use photocraft_cms::{Builtin, Transform, TransformOptions};
+    for depth in [8, 16, 32] {
+        for (mode, profile) in [("rgb", Builtin::DisplayP3), ("gray", Builtin::SGray), ("cmyk", Builtin::CoatedCmyk), ("lab", Builtin::LabD50)] {
+            let mut s = fixture(mode, depth);
+            s.edit("explicit profile", |doc, _| {
+                doc.icc_profile = Some(profile.profile().clone().with_encoded_bytes().to_bytes());
+                Ok(())
+            })
+            .unwrap();
+            let st = s.active().unwrap();
+            let surface = st.doc.layer(st.active_layer.unwrap()).unwrap().surface().unwrap();
+            let format = surface.format();
+            let before = raw(&s);
+            // Independent direct transform from this explicitly chosen source profile,
+            // not the command's profile resolver or its new matching helper.
+            let t = Transform::with_options(profile.profile(), Builtin::LabD50.profile(), TransformOptions::default()).unwrap();
+            let mut lab = [[0.0, 0.0, 0.0, 1.0]; 4];
+            t.convert_f32(&before, format.channels(), lab.as_flattened_mut(), 4, true);
+            let center = [lab[1][0] as f64 * 100.0, lab[1][1] as f64 * 255.0 - 128.0, lab[1][2] as f64 * 255.0 - 128.0];
+            let lo = center.map(|v| v - 0.2);
+            let hi = center.map(|v| v + 0.2);
+            s.execute("image.adjustments.replaceColor", json!({"labMinimum":lo,"labMaximum":hi,"fuzziness":0,"lightness":100})).unwrap();
+            let after = raw(&s);
+            let changed = after.chunks_exact(format.channels()).nth(1).unwrap();
+            let changed = photocraft_raster::to_rgba(&format, changed);
+            assert!(changed[..3].iter().all(|v| *v > 0.97), "{mode}/{depth}: {changed:?}");
+            assert_eq!(&after[..format.channels()], &before[..format.channels()], "black is outside {mode}/{depth}");
+            assert!(s.undo());
+            assert_eq!(raw(&s), before);
+            if mode == "rgb" {
+                let mut srgb = fixture("rgb", depth);
+                let before_srgb = raw(&srgb);
+                srgb.execute("image.adjustments.replaceColor", json!({"labMinimum":lo,"labMaximum":hi,"fuzziness":0,"lightness":100})).unwrap();
+                assert_eq!(raw(&srgb), before_srgb, "the P3 sample must not be mistaken for an sRGB sample");
+            }
+        }
+    }
+}
+
+#[test]
+fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {
+    let mut s = fixture("rgb", 32);
+    let before = raw(&s);
+    let mut expected = before.as_chunks::<4>().0.to_vec();
+    photocraft_algo::tone::replace_color(&mut expected, [0.3, 0.8, 0.2], 40.0, 60.0, 20.0, -10.0);
+    s.execute("image.adjustments.replaceColor", json!({"color":[0.3,0.8,0.2],"fuzziness":40,"hue":60,"saturation":20,"lightness":-10})).unwrap();
+    assert_eq!(raw(&s), expected.as_flattened());
+    let action = photocraft_engine::actions_cmds::Action::new(
+        "Ordinary",
+        vec![("image.adjustments.gradientMap".into(), json!({"stops":[[0,"#000000"],[1,"#ffffff"]]}))],
+    );
+    let (b, _) = atn_cmds::export("Ordinary", &[&action], &[], false).unwrap();
+    assert_eq!(atn::parse(&b).unwrap().actions[0].items[0].event, AtnEvent::Code(*b"GdMp"), "10702 owns the named-event repair");
+}
+
+#[test]
+fn lab_replace_preserves_alpha_and_rejects_locked_or_mismatched_surfaces() {
+    let p = json!({"labMinimum":[0,-128,-128],"labMaximum":[100,127,127],"lightness":100});
+    let mut s = fixture("rgb", 32);
+    let before = raw(&s);
+    s.execute("image.adjustments.replaceColor", p.clone()).unwrap();
+    for (a, b) in raw(&s).chunks_exact(4).zip(before.chunks_exact(4)) {
+        assert_eq!(a[3], b[3]);
+    }
+    assert!(s.undo());
+    s.edit("pixel lock", |doc, active| {
+        doc.layer_mut(active.unwrap()).unwrap().locks.pixels = true;
+        Ok(())
+    })
+    .unwrap();
+    let original = s.active().unwrap().doc.clone();
+    assert!(s.execute("image.adjustments.replaceColor", p.clone()).is_err());
+    assert_eq!(s.active().unwrap().doc, original);
+    let mut mismatch = fixture("rgb", 32);
+    mismatch
+        .edit("inconsistent synthetic mode", |doc, _| {
+            doc.mode = photocraft_doc::ColorMode::Cmyk;
+            Ok(())
+        })
+        .unwrap();
+    let original = mismatch.active().unwrap().doc.clone();
+    assert!(mismatch.execute("image.adjustments.replaceColor", p).is_err());
+    assert_eq!(mismatch.active().unwrap().doc, original);
+}
+
+#[test]
+fn an_unchanged_lab_tone_shift_preserves_native_cmyk_samples() {
+    for depth in [8, 16, 32] {
+        let mut s = fixture("cmyk", depth);
+        s.edit("nontrivial native CMYK", |doc, active| {
+            doc.layer_mut(active.unwrap())
+                .unwrap()
+                .surface_mut()
+                .unwrap()
+                .write_region(photocraft_doc::Rect::from_xywh(1, 0, 1, 1), &[0.2, 0.3, 0.4, 0.25, 1.0]);
+            Ok(())
+        })
+        .unwrap();
+        let before = raw(&s);
+        s.execute("image.adjustments.replaceColor", json!({"labMinimum":[0,-128,-128],"labMaximum":[100,127,127],"hue":0,"saturation":0,"lightness":0}))
+            .unwrap();
+        assert_eq!(raw(&s), before, "an unchanged tone operation must not re-separate CMYK, depth {depth}");
+    }
+}
diff --git a/crates/engine/tests/it/main.rs b/crates/engine/tests/it/main.rs
index f6a8360a4f..60aca0c841 100644
--- a/crates/engine/tests/it/main.rs
+++ b/crates/engine/tests/it/main.rs
@@ -3,6 +3,7 @@
 mod affinity;
 mod artboard_export_names;
 mod atn_crystallize_cell_size;
+mod atn_direct_adjustments;
 mod atn_ripple_amount;
 mod atn_selective_color;
 mod atn_stroke_width;

From 0fb31eb63df6dd3997c61cb0aedc751f28346cfe Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 14:04:20 -0800
Subject: [PATCH 020/109] docs: document supported direct adjustment forms and
 limits

---
 docs/atn.md                | 151 +++++++++++++++++++------------------
 docs/development.md        |  11 +++
 docs/file-format-parity.md |   3 +-
 3 files changed, 92 insertions(+), 73 deletions(-)

diff --git a/docs/atn.md b/docs/atn.md
index 61c2403a19..9b87f2e3df 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -18,7 +18,7 @@ layers and documents, newer and older events and files, and a measured reference
 map yet, with everything needed to implement them without
 the reference application.
 
-## Supported events (117)
+## Supported events (119)
 
 | Code | String ID | Label | PhotoCraft command(s) |
 |---|---|---|---|
@@ -76,6 +76,8 @@ the reference application.
 | `Flip` | flip | Flip | `image.imageRotation.flipCanvasHorizontal`, `image.imageRotation.flipCanvasVertical`, `edit.transform.flipHorizontal`, `edit.transform.flipVertical` |
 | `GsnB` | gaussianBlur | Gaussian Blur | `filter.blur.gaussianBlur` |
 | `GdMp` | gradientMapEvent | Gradient Map | `image.adjustments.gradientMap` |
+| `GrMp` | (code only) | Gradient Map (recorded classic form) | `image.adjustments.gradientMap` |
+| `RplC` | replaceColor | Replace Color (Lab sample box) | `image.adjustments.replaceColor` |
 | `Grow` | grow | Grow | `select.grow` |
 | `Hd  ` | hide | Hide | `layer.hideLayers` |
 | `HghP` | highPass | High Pass | `filter.other.highPass` |
@@ -140,6 +142,81 @@ the reference application.
 | (string ID only) | updatePlacedLayer | Update Smart Objects | `layer.smartObjects.updateModifiedContent` |
 | `Vbrn` | vibrance | Vibrance | `image.adjustments.vibrance` |
 
+### Supported direct adjustment settings
+
+#### Gradient Map (direct)
+
+- Event: `GrMp` (no string ID)
+- PhotoCraft command: `image.adjustments.gradientMap`
+- Supported: classic (`Gcls`, also when omitted), 2..64 ordered custom RGB stops at midpoint 50, smoothness 4096, and the two opaque endpoint transparency stops. Fractional RGB components retain their precision and the recorded name and event survive save.
+- Other interpolation methods, midpoints, transparency, unsorted stops and unsupported descriptor forms remain kept steps. This does not change the separate legacy `GdMp` event mapping.
+
+| Key | String ID | Type | Unit | Default | Allowed |
+|---|---|---|---|---|---|
+| `` | gradientsInterpolationMethod | enumerated |  |  gradientInterpolationMethodType.'Gcls' classic |  |
+| `Grad` | gradient | object |  | obj 'Grdn' gradientClassEvent |  |
+
+Nested values as recorded (defaults):
+```
+    'Nm  ' name : STRINGTYPE = "Vorder- zu Hintergrundfarbe"
+    'GrdF' gradientForm : ENUMERATEDTYPE = 'GrdF' gradientForm.'CstS' customStops
+    'Intr' interfaceIconFrameDimmed : DOUBLETYPE = 4096
+    'Clrs' colors : LISTTYPE = list[2]
+        [0] OBJECTTYPE = obj 'Clrt' colorStop
+            'Clr ' color : OBJECTTYPE = obj 'RGBC' RGBColor
+                'Rd  ' red : DOUBLETYPE = 0
+                'Grn ' green : DOUBLETYPE = 0
+                'Bl  ' blue : DOUBLETYPE = 0
+            'Type' type : ENUMERATEDTYPE = 'Clry' colorStopType.'UsrS' userStop
+            'Lctn' location : INTEGERTYPE = 0
+            'Mdpn' midpoint : INTEGERTYPE = 50
+        [1] OBJECTTYPE = obj 'Clrt' colorStop
+            'Clr ' color : OBJECTTYPE = obj 'RGBC' RGBColor
+                'Rd  ' red : DOUBLETYPE = 255
+                'Grn ' green : DOUBLETYPE = 255
+                'Bl  ' blue : DOUBLETYPE = 255
+            'Type' type : ENUMERATEDTYPE = 'Clry' colorStopType.'UsrS' userStop
+            'Lctn' location : INTEGERTYPE = 4096
+            'Mdpn' midpoint : INTEGERTYPE = 50
+    'Trns' transparency : LISTTYPE = list[2]
+        [0] OBJECTTYPE = obj 'TrnS' transferSpec
+            'Opct' opacity : UNITDOUBLE = 100 '#Prc' percentUnit
+            'Lctn' location : INTEGERTYPE = 0
+            'Mdpn' midpoint : INTEGERTYPE = 50
+        [1] OBJECTTYPE = obj 'TrnS' transferSpec
+            'Opct' opacity : UNITDOUBLE = 100 '#Prc' percentUnit
+            'Lctn' location : INTEGERTYPE = 4096
+            'Mdpn' midpoint : INTEGERTYPE = 50
+```
+
+#### Replace Color
+
+- Event: `RplC` / `replaceColor`
+- PhotoCraft command: `image.adjustments.replaceColor`
+- Supported: the explicit D50 Lab minimum/maximum box and `colorModel` 0, with the four integer settings clamped to the ranges below. Matching uses original pixel channels through the document profile. Unsupported color models, malformed or missing samples and unknown keys remain kept steps.
+- Measured with example values in a prepared document: the Value column shows what was sent and recorded, not a factory default (a step always carries the values the user set).
+
+| Key | String ID | Type | Unit | Example value | Allowed |
+|---|---|---|---|---|---|
+| `Fzns` | fuzziness | integer |  | 40 | 0 .. 200 (out-of-range values are clamped) |
+| `Mnm ` | minimum | object |  | obj 'LbCl' labColor |  |
+| `Mxm ` | maximum | object |  | obj 'LbCl' labColor |  |
+| `H   ` | hue | integer |  | 30 | -180 .. 180 (out-of-range values are clamped) |
+| `Strt` | saturation | integer |  | 0 | -100 .. 100 (out-of-range values are clamped) |
+| `Lght` | lightness | integer |  | 0 | -100 .. 100 (out-of-range values are clamped) |
+| `` | colorModel | integer |  | 0 |  |
+
+Nested values as recorded (example values):
+```
+    'Lmnc' luminance : DOUBLETYPE = 40
+    'A   ' a : DOUBLETYPE = 30
+    'B   ' b : DOUBLETYPE = 40
+    'Lmnc' luminance : DOUBLETYPE = 40
+    'A   ' a : DOUBLETYPE = 30
+    'B   ' b : DOUBLETYPE = 40
+```
+
+
 ## Known gaps in mapped events
 
 A mapped event can still lose a setting. Every mapped event was checked on 2026-11-01: the 5 296 steps of
@@ -1419,7 +1496,7 @@ No parameters: the step carries an empty descriptor.
 
 ### Group E: Video, Other and matting filters and the direct Gradient Map / Replace Color adjustments
 
-All commands exist in PhotoCraft; only the `.atn` mapping is missing. Gradient Map and Replace Color here are the direct adjustments (Image > Adjustments), not adjustment layers (those are already mapped).
+All commands exist in PhotoCraft. The two direct adjustments, classic Gradient Map and Lab-range Replace Color, are supported above; the remaining events below still need their `.atn` mappings. These direct adjustments are separate from adjustment layers.
 
 #### De-Interlace
 
@@ -1462,50 +1539,6 @@ No parameters: the step carries an empty descriptor.
 
 No parameters: the step carries an empty descriptor.
 
-#### Gradient Map (direct)
-
-- Event: `GrMp` (no string ID)
-- PhotoCraft command: `image.adjustments.gradientMap`
-- The `gradient` object is the same gradient form the adjustment layer already maps; reuse that code.
-
-| Key | String ID | Type | Unit | Default | Allowed |
-|---|---|---|---|---|---|
-| `` | gradientsInterpolationMethod | enumerated |  |  gradientInterpolationMethodType.'Gcls' classic |  |
-| `Grad` | gradient | object |  | obj 'Grdn' gradientClassEvent |  |
-
-Nested values as recorded (defaults):
-```
-    'Nm  ' name : STRINGTYPE = "Vorder- zu Hintergrundfarbe"
-    'GrdF' gradientForm : ENUMERATEDTYPE = 'GrdF' gradientForm.'CstS' customStops
-    'Intr' interfaceIconFrameDimmed : DOUBLETYPE = 4096
-    'Clrs' colors : LISTTYPE = list[2]
-        [0] OBJECTTYPE = obj 'Clrt' colorStop
-            'Clr ' color : OBJECTTYPE = obj 'RGBC' RGBColor
-                'Rd  ' red : DOUBLETYPE = 0
-                'Grn ' green : DOUBLETYPE = 0
-                'Bl  ' blue : DOUBLETYPE = 0
-            'Type' type : ENUMERATEDTYPE = 'Clry' colorStopType.'UsrS' userStop
-            'Lctn' location : INTEGERTYPE = 0
-            'Mdpn' midpoint : INTEGERTYPE = 50
-        [1] OBJECTTYPE = obj 'Clrt' colorStop
-            'Clr ' color : OBJECTTYPE = obj 'RGBC' RGBColor
-                'Rd  ' red : DOUBLETYPE = 255
-                'Grn ' green : DOUBLETYPE = 255
-                'Bl  ' blue : DOUBLETYPE = 255
-            'Type' type : ENUMERATEDTYPE = 'Clry' colorStopType.'UsrS' userStop
-            'Lctn' location : INTEGERTYPE = 4096
-            'Mdpn' midpoint : INTEGERTYPE = 50
-    'Trns' transparency : LISTTYPE = list[2]
-        [0] OBJECTTYPE = obj 'TrnS' transferSpec
-            'Opct' opacity : UNITDOUBLE = 100 '#Prc' percentUnit
-            'Lctn' location : INTEGERTYPE = 0
-            'Mdpn' midpoint : INTEGERTYPE = 50
-        [1] OBJECTTYPE = obj 'TrnS' transferSpec
-            'Opct' opacity : UNITDOUBLE = 100 '#Prc' percentUnit
-            'Lctn' location : INTEGERTYPE = 4096
-            'Mdpn' midpoint : INTEGERTYPE = 50
-```
-
 #### Average
 
 - Event: `Avrg` (no string ID)
@@ -1526,32 +1559,6 @@ No parameters: the step carries an empty descriptor.
 | `Ofst` | offset | integer |  | 0 | -9999 .. 9999 (measured in the dialog). Without the dialog the value is ignored |
 | `Mtrx` | matrix | list |  | none: a step always carries all 25 cells | exactly 25 integers (5 x 5, row by row), each -999 .. 999; a 3 x 3 list makes the application fail |
 
-#### Replace Color
-
-- Event: `RplC` / `replaceColor`
-- PhotoCraft command: `image.adjustments.replaceColor`
-- Measured with example values in a prepared document: the Value column shows what was sent and recorded, not a factory default (a step always carries the values the user set).
-
-| Key | String ID | Type | Unit | Example value | Allowed |
-|---|---|---|---|---|---|
-| `Fzns` | fuzziness | integer |  | 40 | 0 .. 200 (out-of-range values are clamped) |
-| `Mnm ` | minimum | object |  | obj 'LbCl' labColor |  |
-| `Mxm ` | maximum | object |  | obj 'LbCl' labColor |  |
-| `H   ` | hue | integer |  | 30 | -180 .. 180 (out-of-range values are clamped) |
-| `Strt` | saturation | integer |  | 0 | -100 .. 100 (out-of-range values are clamped) |
-| `Lght` | lightness | integer |  | 0 | -100 .. 100 (out-of-range values are clamped) |
-| `` | colorModel | integer |  | 0 |  |
-
-Nested values as recorded (example values):
-```
-    'Lmnc' luminance : DOUBLETYPE = 40
-    'A   ' a : DOUBLETYPE = 30
-    'B   ' b : DOUBLETYPE = 40
-    'Lmnc' luminance : DOUBLETYPE = 40
-    'A   ' a : DOUBLETYPE = 30
-    'B   ' b : DOUBLETYPE = 40
-```
-
 ### Group F: Selection combinations, Paste Into/Outside, Fade, Link, Distribute, Define Pattern and older merge/mask events
 
 Steps recorded in an ordinary editing session. The values below were measured in a document set up for each step (a selection, the clipboard, linked or several selected layers). Align, Copy/Paste Layer Style and Rename are already mapped under their current events and are not repeated here.
diff --git a/docs/development.md b/docs/development.md
index 3ecefb9f59..ce77192078 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -631,6 +631,17 @@ PhotoCraft equivalent.
 Events outside the table load as `actions.photoshopStep` steps that keep the descriptor
 verbatim (so Save Actions writes them back) and fail at playback with the step's Photoshop name.
 
+
+Recorded direct Gradient Map (`GrMp`) and Replace Color (`RplC`) forms are described in
+[the ATN reference](atn.md#supported-direct-adjustment-settings), based on davidmann4's
+measurements in #10603. Gradient Map keeps its event, fractional RGB stops and recorded name;
+unsupported interpolation, midpoint and transparency settings remain preserved steps.
+Replace Color accepts `labMinimum` / `labMaximum` (three D50 Lab numbers each), exclusively
+of RGB samples and localized settings. The new option matches native surface samples through
+the document profile, retains alpha and untouched native pixels, and uses one undoable edit.
+A zero tone shift validates its inputs without changing pixels. The existing RGB option keeps
+its previous behavior. Explicit Lab bounds require a composite pixel-layer target.
+
 ## Remove Tool quality
 
 `cargo run --release -p photocraft-engine --example remove_quality -- <dir> [out dir]` fills
diff --git a/docs/file-format-parity.md b/docs/file-format-parity.md
index 1fc994a94e..bbe68a5daf 100644
--- a/docs/file-format-parity.md
+++ b/docs/file-format-parity.md
@@ -133,7 +133,7 @@ remaining gaps in #1606 stay tracked with per-sample corpus ceilings.
 | LUTs `.cube` / `.3dl` / `.look` | R/W (Export Color Lookup) | R/W / R / R | `cms/src/lutfile.rs` |
 | Keyboard shortcuts `.kys` | R/W | R/W | `engine/src/kys.rs` (`write`: Edit › Keyboard Shortcuts › Export…, rows carry our id; Photoshop reading our files is unverified) |
 | ICC profiles | R | R | Own CMS |
-| Actions `.atn` ([reference](atn.md)) | R/W | R/W | `psd/src/atn.rs` (version 16 sets, exact round trip), `engine/src/atn_cmds.rs` (Photoshop events ↔ commands, including Apply Layer Comp by name, #7101; other steps kept verbatim; Save As maps to `file.saveAs`/`file.saveACopy` when its destination is a file, #7102). Panel menu, CLI `batch --actions set.atn`, `actions.load`/`actions.save`. Photoshop 5-era version 12 files unsupported (AUTO-219-2) |
+| Actions `.atn` ([reference](atn.md)) | R/W | R/W | `psd/src/atn.rs` (version 16 sets, exact round trip), `engine/src/atn_cmds.rs` (Photoshop events ↔ commands, including Apply Layer Comp by name, #7101; recorded classic `GrMp` with fractional RGB stops and `RplC` with explicit Lab sample bounds, part of #10607; other steps kept verbatim; Save As maps to `file.saveAs`/`file.saveACopy` when its destination is a file, #7102). Panel menu, CLI `batch --actions set.atn`, `actions.load`/`actions.save`. Photoshop 5-era version 12 files unsupported (AUTO-219-2) |
 | Styles `.asl` | R/W | R/W | `psd/src/asl.rs`, `io/src/asl_map.rs`; Styles panel Import/Export Styles…, `style.presets.importAsl`/`exportAsl` (#1051) |
 | Contours `.shc` | R/W | R/W | `psd/src/shc.rs`; Contour Editor Load…/Save… (FILE-215-15). No user contour library; not yet checked against a Photoshop-written file |
 | Custom shapes `.csh`, tool presets `.tpl` | R/W | no | |
@@ -148,6 +148,7 @@ Embedded SVG and PDF-compatible AI/PDF/EPS payloads can use an explicit VectorCr
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-01 | minor | Recorded direct Gradient Map and Lab-range Replace Color load, play and retain their measured settings on save; unsupported forms remain preserved (part of #10607). |
 | 2026-11-01 | minor | `.atn`: event reference [atn.md](atn.md): the 117 supported events, and measured keys, defaults, ranges and enum values for 101 events not mapped yet |
 | 2026-10-26 | minor | Embedded AI/PDF/EPS save-back retains native format and a separate source-bound display preview; original sources remain undoable. Native Adobe interoperability and standalone EPS/DCS remain unverified; no corpus floor or percentage changed. |
 | 2026-10-22 | minor | Embedded PSD vectors gain explicit bounded SVG editor/save-back; standalone EPS/DCS and native-format fidelity remain open. |

From f39d0b828095e26d8e0d5688bf394fad79c5df46 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 14:06:12 -0800
Subject: [PATCH 021/109] feat(engine): replay the Crop Photos ATN parent once

---
 crates/engine/src/cmd/atn_cmds/events.rs   |   1 +
 crates/engine/src/cmd/atn_cmds/tests.rs    |   2 +
 crates/engine/src/cmd/photo_cmds.rs        |  18 ++--
 crates/engine/tests/it/atn_newer_events.rs | 115 +++++++++++++++++++++
 docs/atn.md                                |  10 ++
 5 files changed, 140 insertions(+), 6 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 55b0e2966b..d5a63f6350 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -476,6 +476,7 @@ pub(super) const EVENTS: &[Event] = &[
     target_event!("textLoadDefaultTypeStyles", "Load Default Type Styles", "type.loadDefaultTypeStyles"),
     target_event!("textSaveDefaultTypeStyles", "Save Default Type Styles", "type.saveDefaultTypeStyles"),
     target_event!("recordMeasurements", "Record Measurements", "image.analysis.recordMeasurements"),
+    target_event!("CropPhotosAuto0001", "Crop and Straighten Photos", "file.automate.cropAndStraightenPhotos"),
     Event { code: "", name: "linkSelectedLayers", label: "Link Layers", ids: &["layer.linkLayers"], from: |d| link_from(d, true), to: |_, p| link_to(p, true) },
     Event {
         code: "",
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 757df349a0..cf677baf5b 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -565,6 +565,8 @@ fn every_mapped_command_exports_and_imports_back() {
         ("type.loadDefaultTypeStyles", json!({})),
         ("type.saveDefaultTypeStyles", json!({})),
         ("image.analysis.recordMeasurements", json!({})),
+        ("file.automate.cropAndStraightenPhotos", json!({})),
+        ("file.automate.cropAndStraightenPhotos", json!({"_atnNoTarget": true})),
         ("layer.new.layerViaCopy", json!({})),
         ("layer.newFillLayer.solidColor", json!({"color": "#336699"})),
         ("layer.newAdjustmentLayer.hueSaturation", json!({})),
diff --git a/crates/engine/src/cmd/photo_cmds.rs b/crates/engine/src/cmd/photo_cmds.rs
index 2aa2a383b8..e5e0b0da69 100644
--- a/crates/engine/src/cmd/photo_cmds.rs
+++ b/crates/engine/src/cmd/photo_cmds.rs
@@ -875,6 +875,7 @@ fn mask_unselected(sel: &Surface, area: Rect, w: usize, h: usize, rgba: &mut [[f
 }
 
 fn crop_and_straighten(s: &mut Session, _p: &Value) -> Result<Value> {
+    crop_ready(s)?;
     let st = s.active().ok_or(EngineError::NoDocument)?;
     let doc = st.doc.clone();
     let fmt = doc.pixel_format();
@@ -942,13 +943,18 @@ fn crop_and_straighten(s: &mut Session, _p: &Value) -> Result<Value> {
 
 // ---------- specs ----------
 
-/// Photoshop greys Crop and Straighten Photos out for Indexed Color documents.
-fn not_indexed(s: &Session) -> std::result::Result<(), String> {
-    let st = s.active().ok_or("no document open")?;
+/// Crop needs a selected, visible, pixel-unlocked layer, including inherited state.
+fn crop_ready(s: &Session) -> Result<()> {
+    let st = s.active().ok_or(EngineError::NoDocument)?;
     if st.doc.mode == ColorMode::Indexed {
-        return Err("not available for Indexed Color documents".into());
+        return Err(EngineError::Other("not available for Indexed Color documents".into()));
     }
-    Ok(())
+    let id = st.active_layer.ok_or_else(|| EngineError::Other("no layer selected".into()))?;
+    let path = st.doc.path_of(id).ok_or(EngineError::NoLayer(id))?;
+    if !st.doc.shown_at(&path) {
+        return Err(EngineError::Other("the selected layer is hidden".into()));
+    }
+    crate::commands::check_pixels_unlocked(&st.doc, id)
 }
 
 fn always(_: &Session) -> std::result::Result<(), String> {
@@ -983,7 +989,7 @@ pub fn specs() -> Vec<CommandSpec> {
             menu: &["File", "Automate"],
             shortcut: None,
             params: "{} → one new document per photo found on the scan (inside the selection when there is one)",
-            enabled: not_indexed,
+            enabled: |s| crop_ready(s).map_err(|e| e.to_string()),
             run: crop_and_straighten,
             journal: true,
         },
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 41f5ed7525..1ecdf41e81 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -223,6 +223,7 @@ const TARGET_EVENTS: &[(&str, &str)] = &[
     ("textLoadDefaultTypeStyles", "type.loadDefaultTypeStyles"),
     ("textSaveDefaultTypeStyles", "type.saveDefaultTypeStyles"),
     ("recordMeasurements", "image.analysis.recordMeasurements"),
+    ("CropPhotosAuto0001", "file.automate.cropAndStraightenPhotos"),
 ];
 
 fn targeted(event: &str, explicit: bool) -> Descriptor {
@@ -307,6 +308,120 @@ fn target_events_keep_unknown_targets_and_refuse_native_options() {
     }
 }
 
+fn scan_fixture() -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 480, "height": 340, "background": "#fafafa"})).unwrap();
+    let st = s.active_mut().unwrap();
+    let id = st.active_layer.unwrap();
+    let surface = Arc::make_mut(&mut st.doc).layer_mut(id).unwrap().surface_mut().unwrap();
+    for (x, y, w, h, color) in [(40, 60, 160, 110, [0.6, 0.1, 0.1, 1.0]), (290, 180, 150, 120, [0.1, 0.2, 0.6, 1.0])] {
+        surface.fill_rect(photocraft_doc::Rect::new(x, y, x + w, y + h), &color);
+    }
+    s.execute("select.rect", json!({"x": 270, "y": 160, "width": 190, "height": 160})).unwrap();
+    s
+}
+
+fn assert_cropped_scan(s: &Session) {
+    assert_eq!(s.documents().len(), 2);
+    let doc = &s.documents()[1].doc;
+    assert!((i64::from(doc.size.width) - 150).abs() <= 4);
+    assert!((i64::from(doc.size.height) - 120).abs() <= 4);
+    let color = doc.layers[0].surface().unwrap().rgba(doc.size.width as i32 / 2, doc.size.height as i32 / 2);
+    assert!(color[2] > 0.5 && color[0] < 0.2, "{color:?}");
+}
+
+#[test]
+fn crop_parent_creates_the_selected_photo_without_changing_the_scan() {
+    for explicit in [false, true] {
+        let mut s = scan_fixture();
+        let source = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        load_targeted(&mut s, "CropPhotosAuto0001", "file.automate.cropAndStraightenPhotos", explicit);
+        assert!(s.is_enabled("file.automate.cropAndStraightenPhotos"));
+        play(&mut s);
+        assert_cropped_scan(&s);
+        assert_eq!(s.documents()[0].doc, source);
+        assert_eq!(s.documents()[0].history.past_len(), history);
+    }
+}
+
+#[test]
+fn crop_parent_refuses_ineligible_layers_without_document_or_history_changes() {
+    for case in ["missing", "stale", "hidden", "hidden-parent", "pixels", "locked-parent", "indexed"] {
+        let mut s = scan_fixture();
+        let st = s.active_mut().unwrap();
+        let id = st.active_layer.unwrap();
+        let doc = Arc::make_mut(&mut st.doc);
+        match case {
+            "missing" => st.active_layer = None,
+            "stale" => st.active_layer = Some(LayerId::fresh()),
+            "hidden" => doc.layer_mut(id).unwrap().visible = false,
+            "pixels" => doc.layer_mut(id).unwrap().locks.pixels = true,
+            "indexed" => doc.mode = photocraft_doc::ColorMode::Indexed,
+            _ => {
+                let mut group = Layer::group("Parent", std::mem::take(&mut doc.layers));
+                group.visible = case != "hidden-parent";
+                group.locks.all = case == "locked-parent";
+                doc.layers.push(group);
+            }
+        }
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        assert!(!s.is_enabled("file.automate.cropAndStraightenPhotos"), "{case}");
+        load_targeted(&mut s, "CropPhotosAuto0001", "file.automate.cropAndStraightenPhotos", false);
+        let report = s.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+        assert_eq!(report["ran"], 0, "{case}: {report}");
+        assert_eq!(report["failed"]["id"], "file.automate.cropAndStraightenPhotos", "{case}: {report}");
+        assert_eq!(s.documents().len(), 1);
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+    assert!(!Session::new().is_enabled("file.automate.cropAndStraightenPhotos"));
+}
+
+#[test]
+fn crop_parent_without_photos_fails_without_creating_documents() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 80, "height": 80, "background": "white"})).unwrap();
+    let before = s.active().unwrap().doc.clone();
+    let history = s.active().unwrap().history.past_len();
+    load_targeted(&mut s, "CropPhotosAuto0001", "file.automate.cropAndStraightenPhotos", false);
+    let report = s.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+    assert_eq!(report["ran"], 0, "{report}");
+    assert!(report["failed"]["error"].as_str().unwrap().contains("no photos found"), "{report}");
+    assert_eq!(s.documents().len(), 1);
+    assert_eq!(s.active().unwrap().doc, before);
+    assert_eq!(s.active().unwrap().history.past_len(), history);
+}
+
+#[test]
+fn crop_parent_runs_once_and_the_kept_helper_stops_the_duplicate_crop_tail() {
+    let mut f = atn::parse(&file("CropPhotosAuto0001", Descriptor::new("cjsp"))).unwrap();
+    let helper = Descriptor::new("null").with("Vl  ", D::List([0.0, 0.0, 150.0, 0.0, 150.0, 120.0, 0.0, 120.0].into_iter().map(D::Double).collect()));
+    f.actions[0].items.push(AtnItem { event: AtnEvent::name("CropPhotos0001"), descriptor: Some(helper.clone()), ..Default::default() });
+    let tail = Action::new("Tail", vec![("image.duplicate".into(), json!({})), ("image.crop".into(), json!({"x": 1, "y": 1, "width": 10, "height": 10}))]);
+    let (bytes, skipped) = atn_cmds::export("Tail", &[&tail], &[], false).unwrap();
+    assert!(skipped.is_empty());
+    f.actions[0].items.extend(atn::parse(&bytes).unwrap().actions[0].items.clone());
+    let mut s = scan_fixture();
+    let source = s.active().unwrap().doc.clone();
+    let report = load(&mut s, &atn::write(&f).unwrap());
+    assert_eq!(report["unsupported"].as_array().unwrap().len(), 1);
+    assert_eq!(
+        s.actions.list[0].steps.iter().map(|step| step.0.as_str()).collect::<Vec<_>>(),
+        ["file.automate.cropAndStraightenPhotos", "actions.photoshopStep", "image.duplicate", "image.crop"]
+    );
+    let saved = s.execute("actions.save", json!({"set": "Links"})).unwrap();
+    let bytes = photocraft_engine::paint::tile::b64_decode(saved["data"].as_str().unwrap()).unwrap();
+    assert_eq!(atn::parse(&bytes).unwrap().actions[0].items[1].descriptor, Some(helper));
+    let report = s.execute("actions.play", json!({"action": "A", "set": "Links"})).unwrap();
+    assert_eq!(report["ran"], 1, "{report}");
+    assert_eq!(report["failed"]["step"], 1);
+    assert_eq!(report["failed"]["id"], "actions.photoshopStep");
+    assert_cropped_scan(&s);
+    assert_eq!(s.documents()[0].doc, source);
+}
+
 #[test]
 fn reverse_linked_selection_and_clear_style_events_do_their_edits() {
     for explicit in [false, true] {
diff --git a/docs/atn.md b/docs/atn.md
index 98a94434a5..69fca5446e 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -33,6 +33,7 @@ are kept as Photoshop steps for lossless saving, rather than partially replayed.
 | `textLoadDefaultTypeStyles` | `type.loadDefaultTypeStyles` |
 | `textSaveDefaultTypeStyles` | `type.saveDefaultTypeStyles` |
 | `recordMeasurements` | `image.analysis.recordMeasurements` |
+| `CropPhotosAuto0001` | `file.automate.cropAndStraightenPhotos` |
 
 These events and Link/Unlink accept either an empty descriptor or an explicit
 current-layer target. Save retains which form was imported. Other targets or
@@ -44,6 +45,15 @@ Isolate Layers toggles the panel view. Type defaults are saved in the current
 session. Record Measurements uses the current selection/ruler/count and data
 point configuration.
 
+Crop and Straighten Photos runs the existing native scan operation once. It
+requires a selected, visible layer with no pixel or full lock, including locks
+and visibility inherited from groups. It creates a document for each detected
+photo within the current selection and leaves the source document unchanged.
+The separately recorded `CropPhotos0001` helper remains a complete kept Photoshop
+step. Playback stops at that unsupported helper before subsequent duplicate/crop
+steps can run. This mapping covers the parent event, not complete recordings
+that contain those generated helper steps.
+
 ## Type to Shape and radius-only Shape Blur
 
 | Photoshop form | PhotoCraft command |

From be36a018460a4ba8f5183e7c5fc1838cf08b2466 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 14:17:28 -0800
Subject: [PATCH 022/109] docs: explain direct adjustment validation helpers

---
 crates/engine/src/cmd/adjust_cmds/replace_color_range.rs   | 1 +
 crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs | 5 +++++
 docs/development.md                                        | 4 ++--
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 058f7e8d4e..c144811812 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -9,6 +9,7 @@ use crate::{EngineError, Result, Session};
 
 const CMD: &str = "image.adjustments.replaceColor";
 
+/// Validate original precision before checking order and converting to native f32.
 fn bound(p: &Value, key: &str) -> Result<[f64; 3]> {
     let values = p.get(key).and_then(Value::as_array).filter(|a| a.len() == 3).ok_or_else(|| bad(CMD, format!("`{key}` must be three finite Lab numbers")))?;
     let mut result = [0.0; 3];
diff --git a/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs b/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
index ace8c22938..a3e0bf4c9e 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_direct_adjustments.rs
@@ -9,10 +9,12 @@ use super::{D, Descriptor, Value, json};
 /// Execution uses ordinary numeric RGB stops, never a stored descriptor.
 pub(super) const GRADIENT_ORIGIN: &str = "__atnGrMp";
 
+/// Refuse extra native settings instead of exporting an incomplete edit.
 fn only_params(p: &Value, allowed: &[&str]) -> bool {
     p.as_object().is_some_and(|p| p.keys().all(|k| allowed.contains(&k.as_str())))
 }
 
+/// Read exactly three channels; callers enforce their colour-space limits.
 fn triple(p: &Value) -> Option<[f64; 3]> {
     let a = p.as_array().filter(|a| a.len() == 3)?;
     Some([a.first()?.as_f64()?, a.get(1)?.as_f64()?, a.get(2)?.as_f64()?])
@@ -102,15 +104,18 @@ pub(super) fn gradient_to(_: &str, p: &Value) -> Option<Descriptor> {
     Some(d)
 }
 
+/// Retain source precision while requiring coordinates to stay finite in native f32.
 fn lab_bound(p: &Value) -> Option<[f64; 3]> {
     let values = triple(p)?;
     values.iter().all(|v| v.is_finite() && (*v as f32).is_finite()).then_some(values)
 }
 
+/// Reject extra, duplicate or reordered keys that the strict writer cannot retain.
 fn ordered(d: &Descriptor, keys: &[&str]) -> bool {
     d.items.len() == keys.len() && d.items.iter().zip(keys).all(|((key, _), expected)| key.is(expected))
 }
 
+/// Read the measured Lab encoding directly, without RGB clipping or type coercion.
 fn lab_from(v: &D) -> Option<[f64; 3]> {
     let D::Descriptor(d) = v else { return None };
     if !d.class_id.is("LbCl") || !d.name.0.is_empty() || !ordered(d, &["Lmnc", "A   ", "B   "]) {
diff --git a/docs/development.md b/docs/development.md
index ce77192078..d7cdbe4edc 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -636,8 +636,8 @@ Recorded direct Gradient Map (`GrMp`) and Replace Color (`RplC`) forms are descr
 [the ATN reference](atn.md#supported-direct-adjustment-settings), based on davidmann4's
 measurements in #10603. Gradient Map keeps its event, fractional RGB stops and recorded name;
 unsupported interpolation, midpoint and transparency settings remain preserved steps.
-Replace Color accepts `labMinimum` / `labMaximum` (three D50 Lab numbers each), exclusively
-of RGB samples and localized settings. The new option matches native surface samples through
+Replace Color accepts `labMinimum` / `labMaximum` (three D50 Lab numbers each), mutually
+exclusive with RGB samples and localized settings. The new option matches native surface samples through
 the document profile, retains alpha and untouched native pixels, and uses one undoable edit.
 A zero tone shift validates its inputs without changing pixels. The existing RGB option keeps
 its previous behavior. Explicit Lab bounds require a composite pixel-layer target.

From 82e613fca8ed79635f740d4c927042617036e815 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 14:34:32 -0800
Subject: [PATCH 023/109] docs: explain ATN adapters and reference survey scope

---
 crates/engine/src/cmd/atn_cmds/events.rs            | 11 +++++++++++
 crates/engine/src/cmd/atn_cmds/steps_make.rs        |  2 ++
 crates/engine/src/cmd/layer_multi_cmds/structure.rs |  1 +
 crates/engine/src/cmd/photo_cmds.rs                 |  1 +
 docs/atn.md                                         |  9 +++++----
 5 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index d5a63f6350..5309d35e45 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -179,6 +179,7 @@ fn clipping_to(_: &str, p: &Value) -> Option<Descriptor> {
 // current-layer target. Save must retain that distinction; native behavior is identical.
 const NO_TARGET: &str = "_atnNoTarget";
 
+/// Accept only bare or current-layer targets, retaining their key-presence distinction for save.
 fn target_params(d: &Descriptor) -> Option<Map<String, Value>> {
     let mut p = Map::new();
     if d.items.is_empty() {
@@ -189,6 +190,7 @@ fn target_params(d: &Descriptor) -> Option<Map<String, Value>> {
     Some(p)
 }
 
+/// Restore the bare or explicit current-layer descriptor selected by the private transport bit.
 fn target_descriptor(p: &Value) -> Option<Descriptor> {
     match p.get(NO_TARGET) {
         None => Some(desc("null").with("null", target_ref("Lyr "))),
@@ -198,14 +200,17 @@ fn target_descriptor(p: &Value) -> Option<Descriptor> {
 }
 
 // Native-parameter allowlist adapted from #10628; refuse unrepresented options on export.
+/// Refuse native options that the selected Photoshop form cannot represent.
 fn params(p: &Value, allowed: &[&str]) -> bool {
     p.as_object().is_some_and(|p| p.keys().all(|key| allowed.contains(&key.as_str())))
 }
 
+/// Import a target-only event, refusing other targets and extra descriptor settings.
 fn target_only_from(d: &Descriptor, id: &str) -> Mapped {
     target_params(d).map_or(Mapped::Unsupported { harmless: false }, |p| step(id, Value::Object(p)))
 }
 
+/// Export a current-target native step only when no unrepresented options are present.
 fn target_only_to(_: &str, p: &Value) -> Option<Descriptor> {
     if !params(p, &[NO_TARGET]) {
         return None;
@@ -215,6 +220,7 @@ fn target_only_to(_: &str, p: &Value) -> Option<Descriptor> {
 
 const SHAPE_BLUR: &[F] = &[F("Rds ", "radius", Kind::Px)];
 
+/// Map the radius-only Shape Blur form; keep custom assets or extra keys unsupported.
 fn shape_blur_from(d: &Descriptor) -> Mapped {
     let unsupported = Mapped::Unsupported { harmless: false };
     let Some(p) = fields_from(d, SHAPE_BLUR) else { return unsupported };
@@ -222,6 +228,7 @@ fn shape_blur_from(d: &Descriptor) -> Mapped {
     if shape_blur_to("filter.blur.shapeBlur", &p).is_some_and(|expected| d.items == expected.items) { step("filter.blur.shapeBlur", p) } else { unsupported }
 }
 
+/// Write an optional finite 5–1000 pixel radius, refusing explicit shapes and other options.
 fn shape_blur_to(_: &str, p: &Value) -> Option<Descriptor> {
     if !params(p, &["radius"]) {
         return None;
@@ -237,12 +244,14 @@ fn shape_blur_to(_: &str, p: &Value) -> Option<Descriptor> {
 
 // Recorded Link and Unlink need explicit state: replaying the UI toggle can
 // perform the opposite operation. Target matching follows #10628's adapter.
+/// Import Link or Unlink as an explicit operation rather than the state-dependent UI toggle.
 fn link_from(d: &Descriptor, linked: bool) -> Mapped {
     let Some(mut p) = target_params(d) else { return Mapped::Unsupported { harmless: false } };
     p.insert("linked".into(), Value::Bool(linked));
     step("layer.linkLayers", Value::Object(p))
 }
 
+/// Export only the matching explicit link state and supported current-layer target form.
 fn link_to(p: &Value, linked: bool) -> Option<Descriptor> {
     if !params(p, &["linked", NO_TARGET]) || p.get("linked") != Some(&Value::Bool(linked)) {
         return None;
@@ -250,6 +259,7 @@ fn link_to(p: &Value, linked: bool) -> Option<Descriptor> {
     target_descriptor(p)
 }
 
+/// Map canonical Smart Object file descriptors, refusing unrepresented paths, targets or keys.
 fn smart_path_from(d: &Descriptor, id: &str) -> Mapped {
     let unsupported = Mapped::Unsupported { harmless: false };
     let key = if id == "layer.smartObjects.convertToLinked" { "Usng" } else { "null" };
@@ -269,6 +279,7 @@ fn smart_path_from(d: &Descriptor, id: &str) -> Mapped {
     if d.items == expected.items { step(id, p) } else { unsupported }
 }
 
+/// Export path-only native parameters using the existing Open/Place path encoding.
 fn smart_path_to(id: &str, p: &Value) -> Option<Descriptor> {
     let p = p.as_object()?;
     let path = p.get("path")?.as_str()?;
diff --git a/crates/engine/src/cmd/atn_cmds/steps_make.rs b/crates/engine/src/cmd/atn_cmds/steps_make.rs
index 098bd6ab9a..a1525c6953 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_make.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_make.rs
@@ -143,6 +143,7 @@ fn type_shape_descriptor() -> Descriptor {
     desc("null").with("null", class_ref("contentLayer")).with("Usng", target_ref("textLayer"))
 }
 
+/// Map supported Make forms, including the exact target-text-to-content-layer references.
 pub(super) fn make_from(d: &Descriptor) -> Mapped {
     if d.items == type_shape_descriptor().items {
         return none("type.convertToShape");
@@ -230,6 +231,7 @@ pub(super) fn make_from(d: &Descriptor) -> Mapped {
     }
 }
 
+/// Build supported Make descriptors; Type to Shape exports only without native options.
 pub(super) fn make_to(id: &str, p: &Value) -> Option<Descriptor> {
     if id == "type.convertToShape" {
         return p.as_object().filter(|p| p.is_empty()).map(|_| type_shape_descriptor());
diff --git a/crates/engine/src/cmd/layer_multi_cmds/structure.rs b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
index c52f7a3a1d..f5d4b2325f 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/structure.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
@@ -3,6 +3,7 @@ use super::{Document, EngineError, Layer, LayerContent, LayerId, PixelFormat, Re
 
 // ---------- structural commands ----------
 
+/// Set an explicit link state idempotently, or toggle when omitted, with singleton cleanup and Undo.
 pub(super) fn link_layers(s: &mut Session, p: &Value) -> Result<Value> {
     let requested = match p.get("linked") {
         None => None,
diff --git a/crates/engine/src/cmd/photo_cmds.rs b/crates/engine/src/cmd/photo_cmds.rs
index e5e0b0da69..9dd7da094b 100644
--- a/crates/engine/src/cmd/photo_cmds.rs
+++ b/crates/engine/src/cmd/photo_cmds.rs
@@ -874,6 +874,7 @@ fn mask_unselected(sel: &Surface, area: Rect, w: usize, h: usize, rgba: &mut [[f
     true
 }
 
+/// Validate the selected layer, then open cropped scan photos without editing the source document.
 fn crop_and_straighten(s: &mut Session, _p: &Value) -> Result<Value> {
     crop_ready(s)?;
     let st = s.active().ok_or(EngineError::NoDocument)?;
diff --git a/docs/atn.md b/docs/atn.md
index 6d5b86ec7e..1c3518c3f6 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -206,7 +206,7 @@ run. This covers the parent event, not complete recordings with generated helper
 
 ## Known gaps in mapped events
 
-A mapped event can still lose a setting. Every mapped event was checked on 2026-11-01: the 5 296 steps of
+A mapped event can still lose a setting. The original 117-event mapping was checked on 2026-11-01: the 5 296 steps of
 the `.atn` corpus (sets the reference application recorded) and factory descriptors measured in the
 reference application went through `actions.load` and `actions.save`, and each saved descriptor was compared
 with the original. Then every step PhotoCraft saves for the cases in
@@ -642,12 +642,13 @@ and class `null` that version 16 files use for code events; nested classes get t
 keeps writing version 16. Version 7 files (a different layout with 8-bit strings) and sets wrapped in
 MacBinary stay rejected.
 
-## Event reference: events not mapped yet
+## Event reference: original unmapped events
 
-Each entry below is an event the reference application records that PhotoCraft does not map yet: its
+Each entry below describes an event that was unmapped in the original reference survey: its
 4-character code and string ID, the PhotoCraft command it should map to, and every key the step carries,
 in the order it is recorded, with type, unit, factory default and allowed values. When an event is
-implemented, move it to the table above in the same change.
+implemented, add it to the supported table while retaining the measured reference.
+Current support and limits are described under [Newer event mapping boundaries](#newer-event-mapping-boundaries).
 
 ### How these values were measured
 

From 75ab50544e4828fdbdcf871c972941b06582e1f6 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 15:14:44 -0800
Subject: [PATCH 024/109] Limit Lab Replace Color work to selected bounds

---
 .../cmd/adjust_cmds/replace_color_range.rs    | 33 ++++++++++++++++++-
 .../engine/tests/it/atn_direct_adjustments.rs | 19 ++++++++---
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index c144811812..3bb6cf312c 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -2,6 +2,8 @@
 use photocraft_algo::{selection, tone};
 use photocraft_cms::{Builtin, TransformOptions};
 use photocraft_doc::SampleType;
+use photocraft_geom::Rect;
+use photocraft_raster::Surface;
 use serde_json::Value;
 
 use super::{bad, num};
@@ -9,6 +11,14 @@ use crate::{EngineError, Result, Session};
 
 const CMD: &str = "image.adjustments.replaceColor";
 
+/// Unstored pixels can still be selected when the mask has a nonzero default.
+fn edit_bounds(content: Rect, selected: Option<&Surface>) -> Rect {
+    match selected {
+        Some(mask) if mask.default_pixel().first() == Some(&0.0) => content.intersect(&mask.content_bounds()),
+        _ => content,
+    }
+}
+
 /// Validate original precision before checking order and converting to native f32.
 fn bound(p: &Value, key: &str) -> Result<[f64; 3]> {
     let values = p.get(key).and_then(Value::as_array).filter(|a| a.len() == 3).ok_or_else(|| bad(CMD, format!("`{key}` must be three finite Lab numbers")))?;
@@ -72,7 +82,7 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
     s.edit("Replace Color", |doc, _| {
         let selected = doc.selection.clone();
         let surface = crate::commands::paint_surface(doc, id, &Value::Null)?;
-        let rect = surface.content_bounds();
+        let rect = edit_bounds(surface.content_bounds(), selected.as_ref());
         if rect.is_empty() {
             return Ok(Value::Null);
         }
@@ -112,3 +122,24 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
     })
     .map(Some)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use photocraft_color::PixelFormat;
+
+    #[test]
+    fn selected_work_bounds_preserve_implicit_selection_and_clip_explicit_pixels() {
+        let content = Rect::new(-100, -100, 100, 100);
+        let mut mask = Surface::new(PixelFormat::GRAY8);
+        assert_eq!(edit_bounds(content, Some(&mask)), Rect::EMPTY);
+        mask.fill_rect(Rect::new(98, 96, 110, 105), &[0.5]);
+        assert_eq!(edit_bounds(content, Some(&mask)), Rect::new(98, 96, 100, 100));
+        assert_eq!(edit_bounds(content, None), content);
+        for coverage in [0.5, 1.0] {
+            let mut mask = Surface::with_default(PixelFormat::GRAY8, &[coverage]);
+            mask.fill_rect(Rect::new(2, 2, 3, 3), &[0.0]);
+            assert_eq!(edit_bounds(content, Some(&mask)), content, "stored holes do not bound selected pixels");
+        }
+    }
+}
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 3cefe7ba0a..7678eb99c7 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -336,7 +336,7 @@ fn invalid_replace_descriptors_and_lossy_exports_are_refused() {
 
 #[test]
 fn recorded_replace_color_clamps_shifts_and_plays_the_lab_box_at_every_depth() {
-    for depth in [8, 16, 32] {
+    for (depth, inverse) in [8, 16, 32].into_iter().flat_map(|depth| [(depth, false), (depth, true)]) {
         let mut d = replace();
         for key in ["Mnm ", "Mxm "] {
             let o = object(&mut d, key);
@@ -353,13 +353,24 @@ fn recorded_replace_color_clamps_shifts_and_plays_the_lab_box_at_every_depth() {
         assert_eq!(imported.actions[0].steps[0].1["lightness"], 100);
         let mut s = fixture("lab", depth);
         set_lab_pixels(&mut s);
-        s.execute("select.rect", json!({"x":0,"y":0,"width":2,"height":1})).unwrap();
+        s.execute("select.rect", json!({"x":1,"y":0,"width":1,"height":1})).unwrap();
+        if inverse {
+            let mut mask = photocraft_raster::Surface::with_default(photocraft_doc::PixelFormat::GRAY8, &[1.0]);
+            mask.fill_rect(photocraft_doc::Rect::new(1, 0, 2, 1), &[0.0]);
+            std::sync::Arc::make_mut(&mut s.active_mut().unwrap().doc).selection = Some(mask);
+        }
         let before = raw(&s);
         s.actions.list = imported.actions;
         play(&mut s);
         let after = raw(&s);
-        assert!(after[0] > 0.99 && after[4] > 0.99);
-        assert_eq!(&after[8..], &before[8..], "selection must bound the edit");
+        if inverse {
+            assert!(after[0] > 0.99 && after[8] > 0.99);
+            assert_eq!(&after[4..8], &before[4..8], "the selection hole must stay unchanged");
+        } else {
+            assert!(after[4] > 0.99);
+            assert_eq!(&after[..4], &before[..4], "pixels before the selection must stay unchanged");
+            assert_eq!(&after[8..], &before[8..], "pixels after the selection must stay unchanged");
+        }
         assert!(s.undo());
         assert_eq!(raw(&s), before);
         let descriptor = saved(&s).descriptor.unwrap();

From e6f23fd8e235247b8ec0ef5360718bfe3838817a Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 15:26:29 -0800
Subject: [PATCH 025/109] feat(engine): map limited Artboard-from-Group ATN
 forms

Preserve the target-only call and exactly reconstruct empty-guide settings. Apply preset tags without resizing, retain fractional RGB, and refuse unresolved guide state before mutation. Nonempty associations and unproved flag values remain unfinished.
---
 crates/engine/src/cmd/artboard_cmds.rs        |  23 +++-
 crates/engine/src/cmd/atn_cmds.rs             |   1 +
 crates/engine/src/cmd/atn_cmds/events.rs      |   9 ++
 .../engine/src/cmd/atn_cmds/steps_artboard.rs |  65 ++++++++++
 crates/engine/src/cmd/atn_cmds/tests.rs       |   2 +
 crates/engine/tests/it/atn_newer_events.rs    | 122 ++++++++++++++++++
 docs/atn.md                                   |  20 ++-
 7 files changed, 234 insertions(+), 8 deletions(-)
 create mode 100644 crates/engine/src/cmd/atn_cmds/steps_artboard.rs

diff --git a/crates/engine/src/cmd/artboard_cmds.rs b/crates/engine/src/cmd/artboard_cmds.rs
index 2f05ddfae0..89e7a15d00 100644
--- a/crates/engine/src/cmd/artboard_cmds.rs
+++ b/crates/engine/src/cmd/artboard_cmds.rs
@@ -301,18 +301,35 @@ fn new_artboard(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({"layer": id.0, "rect": [rect.x0, rect.y0, rect.width(), rect.height()]}))
 }
 
+/// Convert a plain group without resizing its content bounds; refuse unresolved recorded guide associations before editing.
 fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
+    let cmd = "layer.new.artboardFromGroup";
     let d = s.active().ok_or(EngineError::NoDocument)?;
     let id = p.get("layer").and_then(Value::as_u64).map(LayerId).or(d.active_layer).ok_or(EngineError::Other("no active layer".into()))?;
+    let preset = match p.get("preset") {
+        None => String::new(),
+        Some(value) => value.as_str().ok_or_else(|| bad(cmd, "preset must be text"))?.to_string(),
+    };
+    if p.get("changeBackground").is_some_and(|value| value != &Value::Bool(true)) {
+        return Err(bad(cmd, "only an explicit true background-change flag is supported"));
+    }
+    if let Some(guides) = p.get("guideIDs") {
+        if !guides.as_array().is_some_and(Vec::is_empty) {
+            return Err(bad(cmd, "recorded guide associations are not supported"));
+        }
+        if !d.doc.guides.horizontal.is_empty() || !d.doc.guides.vertical.is_empty() {
+            return Err(bad(cmd, "an explicit empty guide association requires a document without guides"));
+        }
+    }
     let canvas = d.doc.bounds();
-    let background = background_param(p, "layer.new.artboardFromGroup")?.unwrap_or_default();
+    let background = background_param(p, cmd)?.unwrap_or_default();
     let rect = s.edit("Artboard from Group", |doc, active| {
         if !doc.layers.iter().any(|t| t.id == id && t.is_group() && t.artboard().is_none()) {
             return Err(EngineError::Other("artboards are made from a top-level layer group".into()));
         }
         let l = doc.layer_mut(id).ok_or(EngineError::NoLayer(id))?;
         let rect = crate::layer_multi_cmds::layer_bounds(l).unwrap_or(canvas);
-        set_artboard(l, Artboard { rect, background, preset: String::new() });
+        set_artboard(l, Artboard { rect, background, preset });
         fit_canvas(doc);
         *active = Some(id);
         Ok(rect)
@@ -703,7 +720,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "layer.new.artboardFromGroup",
             "Artboard from Group…",
             &["Layer", "New"],
-            r##"{"layer":id? (a top-level group; default active),"background":…?} → {layer, rect}"##,
+            r##"{"layer":id? (a top-level group; default active),"background":…?,"color":[r,g,b]|"#rrggbb"?,"preset":str? (tag only; does not resize),"guideIDs":[]? (recorded empty association; requires no document guides),"changeBackground":true? (recorded apply flag; other values refused)} → {layer, rect}"##,
             has_plain_group,
             artboard_from_group
         ),
diff --git a/crates/engine/src/cmd/atn_cmds.rs b/crates/engine/src/cmd/atn_cmds.rs
index 42a4722479..c0e6ed5712 100644
--- a/crates/engine/src/cmd/atn_cmds.rs
+++ b/crates/engine/src/cmd/atn_cmds.rs
@@ -32,6 +32,7 @@ mod descriptors;
 mod events;
 mod fields;
 mod files;
+mod steps_artboard;
 mod steps_doc;
 mod steps_image;
 mod steps_layer;
diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 5309d35e45..a80056260d 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -2,6 +2,7 @@ const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
 use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, path_text, path_value, ref_class, target_ref};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
+use super::steps_artboard::{artboard_from, artboard_to};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
     crop_from, crop_to, export_from, export_to, image_size_from, image_size_to, merge_visible_from, merge_visible_to, open_from, open_to, paste_from, paste_to,
@@ -488,6 +489,14 @@ pub(super) const EVENTS: &[Event] = &[
     target_event!("textSaveDefaultTypeStyles", "Save Default Type Styles", "type.saveDefaultTypeStyles"),
     target_event!("recordMeasurements", "Record Measurements", "image.analysis.recordMeasurements"),
     target_event!("CropPhotosAuto0001", "Crop and Straighten Photos", "file.automate.cropAndStraightenPhotos"),
+    Event {
+        code: "",
+        name: "artboardFromLayerGroupEvent",
+        label: "Artboard from Group",
+        ids: &["layer.new.artboardFromGroup"],
+        from: artboard_from,
+        to: artboard_to,
+    },
     Event { code: "", name: "linkSelectedLayers", label: "Link Layers", ids: &["layer.linkLayers"], from: |d| link_from(d, true), to: |_, p| link_to(p, true) },
     Event {
         code: "",
diff --git a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
new file mode 100644
index 0000000000..8d2964d95a
--- /dev/null
+++ b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
@@ -0,0 +1,65 @@
+//! Strict Artboard from Group forms whose settings the existing native model can apply.
+
+use super::descriptors::{desc, get_num, get_obj, get_text, target_ref, text};
+use super::fields::{Mapped, none, step};
+use super::{D, Descriptor, Value, json};
+
+const COMMAND: &str = "layer.new.artboardFromGroup";
+
+/// Import the current-target form or the verified empty-guide settings form, keeping other forms whole.
+pub(super) fn artboard_from(d: &Descriptor) -> Mapped {
+    let unsupported = Mapped::Unsupported { harmless: false };
+    if d.items == desc("null").with("null", target_ref("Lyr ")).items {
+        return none(COMMAND);
+    }
+    let Some(board) = get_obj(d, "artboard") else { return unsupported };
+    let Some(color) = get_obj(board, "Clr ") else { return unsupported };
+    let Some(preset) = get_text(board, "artboardPresetName") else { return unsupported };
+    let background = match board.get("artboardBackgroundType") {
+        Some(D::Integer(1)) => "white",
+        Some(D::Integer(2)) => "black",
+        Some(D::Integer(3)) => "transparent",
+        Some(D::Integer(4)) => "custom",
+        _ => return unsupported,
+    };
+    let rgb: Option<Vec<f64>> = ["Rd  ", "Grn ", "Bl  "].iter().map(|key| get_num(color, key).map(|n| n / 255.0)).collect();
+    let Some(rgb) = rgb else { return unsupported };
+    let p = json!({"background": background, "color": rgb, "preset": preset, "guideIDs": [], "changeBackground": true});
+    // Reconstruction checks every ordered key, nested class, value type and the evidenced flag.
+    if artboard_to(COMMAND, &p).is_some_and(|expected| expected.items == d.items) { step(COMMAND, p) } else { unsupported }
+}
+
+/// Export only current-target steps or complete, representable empty-guide settings without quantizing RGB.
+pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
+    let p = p.as_object()?;
+    let d = desc("null").with("null", target_ref("Lyr "));
+    if p.is_empty() {
+        return Some(d);
+    }
+    if p.len() != 5 || p.get("changeBackground") != Some(&Value::Bool(true)) || !p.get("guideIDs")?.as_array()?.is_empty() {
+        return None;
+    }
+    let preset = p.get("preset")?.as_str()?;
+    let background = match p.get("background")?.as_str()? {
+        "white" => 1,
+        "black" => 2,
+        "transparent" => 3,
+        "custom" => 4,
+        _ => return None,
+    };
+    let rgb = p.get("color")?.as_array()?;
+    if rgb.len() != 3 {
+        return None;
+    }
+    let rgb: Vec<f64> = rgb.iter().map(Value::as_f64).collect::<Option<_>>()?;
+    if !rgb.iter().all(|n| n.is_finite() && (0.0..=1.0).contains(n)) {
+        return None;
+    }
+    let color = ["Rd  ", "Grn ", "Bl  "].into_iter().zip(rgb).fold(desc("RGBC"), |d, (key, n)| d.with(key, D::Double(n * 255.0)));
+    let board = desc("artboard")
+        .with("guideIDs", D::List(vec![]))
+        .with("artboardPresetName", text(preset))
+        .with("Clr ", D::Descriptor(color))
+        .with("artboardBackgroundType", D::Integer(background));
+    Some(d.with("artboard", D::Descriptor(board)).with("changeBackground", D::Integer(1)))
+}
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index cf677baf5b..d47a0a0d49 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -567,6 +567,8 @@ fn every_mapped_command_exports_and_imports_back() {
         ("image.analysis.recordMeasurements", json!({})),
         ("file.automate.cropAndStraightenPhotos", json!({})),
         ("file.automate.cropAndStraightenPhotos", json!({"_atnNoTarget": true})),
+        ("layer.new.artboardFromGroup", json!({})),
+        ("layer.new.artboardFromGroup", json!({"background":"white","color":[1,1,1],"preset":"","guideIDs":[],"changeBackground":true})),
         ("layer.new.layerViaCopy", json!({})),
         ("layer.newFillLayer.solidColor", json!({"color": "#336699"})),
         ("layer.newAdjustmentLayer.hueSaturation", json!({})),
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 1ecdf41e81..ed63f3d333 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -422,6 +422,128 @@ fn crop_parent_runs_once_and_the_kept_helper_stops_the_duplicate_crop_tail() {
     assert_eq!(s.documents()[0].doc, source);
 }
 
+/// Two sparse marks leave a transparent gap where the converted board's background is observable.
+fn artboard_fixture() -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 12, "height": 10, "background": "transparent"})).unwrap();
+    let st = s.active_mut().unwrap();
+    let doc = Arc::make_mut(&mut st.doc);
+    let mut child = Layer::raster("Pixels", doc.pixel_format());
+    let surface = child.surface_mut().unwrap();
+    for rect in [photocraft_doc::Rect::new(2, 2, 3, 3), photocraft_doc::Rect::new(5, 5, 6, 6)] {
+        surface.fill_rect(rect, &[1.0, 0.0, 0.0, 1.0]);
+    }
+    let group = Layer::group("Group", vec![child]);
+    let id = group.id;
+    doc.layers = vec![group];
+    s.restore_layer_selection(Some(id), &[id], Some(id)).unwrap();
+    s
+}
+
+/// The reference's ordered settings keys, with fractional RGB that must not be rounded to hex.
+fn artboard_descriptor(background: i32, guides: Vec<D>, flag: D) -> Descriptor {
+    let color = Descriptor::new("RGBC").with("Rd  ", D::Double(63.75)).with("Grn ", D::Double(127.5)).with("Bl  ", D::Double(191.25));
+    let board = Descriptor::new("artboard")
+        .with("guideIDs", D::List(guides))
+        .with("artboardPresetName", D::Text(UnicodeString::new_nul("iPhone 14")))
+        .with("Clr ", D::Descriptor(color))
+        .with("artboardBackgroundType", D::Integer(background));
+    Descriptor::new("null").with("null", target()).with("artboard", D::Descriptor(board)).with("changeBackground", flag)
+}
+
+/// Conversion preserves the group's geometry/content while applying every admitted setting and Undo.
+#[test]
+fn artboard_empty_guide_settings_roundtrip_apply_background_and_preset_without_resizing() {
+    for (background, expected) in [(1, [1.0, 1.0, 1.0, 1.0]), (2, [0.0, 0.0, 0.0, 1.0]), (3, [0.0; 4]), (4, [0.25, 0.5, 0.75, 1.0])] {
+        let mut s = artboard_fixture();
+        let before = s.active().unwrap().doc.clone();
+        let id = s.active().unwrap().active_layer.unwrap();
+        let d = artboard_descriptor(background, vec![], D::Integer(1));
+        assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"], json!([]));
+        assert_eq!(s.actions.list[0].steps[0].0, "layer.new.artboardFromGroup");
+        assert_eq!(s.actions.list[0].steps[0].1["color"], json!([0.25, 0.5, 0.75]));
+        assert_eq!(saved_item(&mut s).descriptor, Some(d));
+        play(&mut s);
+        let doc = &s.active().unwrap().doc;
+        let board = doc.layer(id).unwrap().artboard().unwrap();
+        assert_eq!(board.rect, photocraft_doc::Rect::new(2, 2, 6, 6), "preset is a tag, not a request to resize the group");
+        assert_eq!(board.preset, "iPhone 14");
+        assert_eq!(doc.size, before.size);
+        assert_eq!(doc.layer(id).unwrap().children(), before.layer(id).unwrap().children());
+        let pixel = photocraft_compose::render(doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0];
+        for (actual, expected) in pixel.into_iter().zip(expected) {
+            assert!((actual - expected).abs() < 0.005, "background {background}: {pixel:?}");
+        }
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+/// The target-only call uses the existing menu behavior without synthesizing settings.
+#[test]
+fn artboard_target_only_form_keeps_existing_native_group_behavior() {
+    let mut s = artboard_fixture();
+    let before = s.active().unwrap().doc.clone();
+    let d = Descriptor::new("null").with("null", target());
+    assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"], json!([]));
+    assert_eq!(s.actions.list[0].steps, [("layer.new.artboardFromGroup".into(), json!({}))]);
+    assert_eq!(saved_item(&mut s).descriptor, Some(d));
+    play(&mut s);
+    assert!(s.active().unwrap().doc.layers[0].artboard().is_some());
+    assert!(s.undo());
+    assert_eq!(s.active().unwrap().doc, before);
+}
+
+/// Unproved settings remain byte-preserving kept steps and cannot partially edit the document.
+#[test]
+fn artboard_unproven_associations_flags_and_extra_settings_stay_whole() {
+    for d in [
+        artboard_descriptor(1, vec![D::Integer(7)], D::Integer(1)),
+        artboard_descriptor(1, vec![], D::Integer(0)),
+        artboard_descriptor(1, vec![], D::Integer(2)),
+        artboard_descriptor(1, vec![], D::Boolean(true)),
+        artboard_descriptor(5, vec![], D::Integer(1)),
+        artboard_descriptor(1, vec![], D::Integer(1)).with("extra", D::Boolean(true)),
+        Descriptor::new("null"),
+    ] {
+        let mut s = artboard_fixture();
+        assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"].as_array().unwrap().len(), 1);
+        assert_eq!(saved_item(&mut s).descriptor, Some(d));
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        let report = s.execute("actions.play", json!({"action":"A","set":"Links"})).unwrap();
+        assert_eq!(report["ran"], 0, "{report}");
+        assert_eq!(report["failed"]["id"], "actions.photoshopStep");
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+    for p in [json!({"layer":1}), json!({"preset":"iPhone 14"}), json!({"guideIDs":[]}), json!({"changeBackground":false})] {
+        let action = Action::new("A", vec![("layer.new.artboardFromGroup".into(), p)]);
+        assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
+    }
+}
+
+/// An explicit empty association cannot silently acquire the document's spatially inferred guides.
+#[test]
+fn artboard_empty_association_refuses_existing_guides_before_editing() {
+    let mut s = artboard_fixture();
+    Arc::make_mut(&mut s.active_mut().unwrap().doc).guides.horizontal.push(3.0);
+    let before = s.active().unwrap().doc.clone();
+    let history = s.active().unwrap().history.past_len();
+    assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", artboard_descriptor(4, vec![], D::Integer(1))))["unsupported"], json!([]));
+    let report = s.execute("actions.play", json!({"action":"A","set":"Links"})).unwrap();
+    assert_eq!(report["ran"], 0, "{report}");
+    assert_eq!(report["failed"]["id"], "layer.new.artboardFromGroup");
+    assert!(report["failed"]["error"].as_str().unwrap().contains("without guides"));
+    assert_eq!(s.active().unwrap().doc, before);
+    assert_eq!(s.active().unwrap().history.past_len(), history);
+    for p in [json!({"guideIDs":[7]}), json!({"guideIDs":false}), json!({"changeBackground":false}), json!({"preset":7})] {
+        assert!(s.execute("layer.new.artboardFromGroup", p).is_err());
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+}
+
 #[test]
 fn reverse_linked_selection_and_clear_style_events_do_their_edits() {
     for explicit in [false, true] {
diff --git a/docs/atn.md b/docs/atn.md
index 1c3518c3f6..86ecf7f311 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -18,7 +18,7 @@ layers and documents, newer and older events and files, and a measured reference
 map yet, with everything needed to implement them without
 the reference application.
 
-## Supported events (138)
+## Supported events (139)
 
 | Code | String ID | Label | PhotoCraft command(s) |
 |---|---|---|---|
@@ -160,13 +160,23 @@ the reference application.
 | (string ID only) | placedLayerRelinkToFile | Relink to File | `layer.smartObjects.relinkToFile` |
 | (string ID only) | placedLayerReplaceContents | Replace Contents | `layer.smartObjects.replaceContents` |
 | (string ID only) | shapeBlur | Shape Blur (radius-only form) | `filter.blur.shapeBlur` |
+| (string ID only) | artboardFromLayerGroupEvent | Artboard from Group (limited forms below) | `layer.new.artboardFromGroup` |
 
 ### Newer event mapping boundaries
 
-The two **Measured** tables under [Newer events](#newer-events-string-id-only)
-now map except for `artboardFromLayerGroupEvent`. Its `guideIDs` association and
-`changeBackground` behavior are not established by the reference, so the whole
-step remains kept. No guide IDs are discarded or guessed.
+Twenty-two of the 23 requested forms in the two **Measured** tables under
+[Newer events](#newer-events-string-id-only) are fully mapped. Artboard from Group
+has an intermediate mapping for the canonical current-layer target alone, or a
+complete settings object with empty `guideIDs` and integer `changeBackground: 1`.
+The latter requires a document without guides, so the existing spatial guide
+export cannot manufacture an association. The preset is retained as a tag without
+resizing the group; RGB background channels retain fractional values. Only forms
+that reconstruct exactly are admitted. Unrepresented native options refuse export.
+
+Nonempty guide associations and other flag values remain complete kept steps.
+The Artboard row is still unfinished: [Adobe documents guide IDs as object identities](https://developer.adobe.com/photoshop/uxp/2022/ps-reference/classes/guide),
+separate from list positions, and the current native model has no corresponding
+identity/ownership binding. No guide ID is discarded or treated as an array index.
 
 The sixteen target-only events accept an empty descriptor or the current-layer
 `null` reference (`Lyr `/`Ordn.Trgt`). Save retains which form was imported.

From 3fa3d344618df5c97ae34e9f83c8de1023741360 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 15:32:13 -0800
Subject: [PATCH 026/109] Describe adjustment test invariants and conversion
 boundaries

---
 crates/engine/src/cmd/adjust_cmds.rs               |  1 +
 .../src/cmd/adjust_cmds/replace_color_range.rs     |  1 +
 crates/engine/src/cmd/atn_cmds/adjustments.rs      |  1 +
 crates/engine/src/cmd/atn_cmds/tests.rs            |  1 +
 crates/engine/tests/it/atn_direct_adjustments.rs   | 14 ++++++++++++++
 5 files changed, 18 insertions(+)

diff --git a/crates/engine/src/cmd/adjust_cmds.rs b/crates/engine/src/cmd/adjust_cmds.rs
index cabad771b8..2121eeafa2 100644
--- a/crates/engine/src/cmd/adjust_cmds.rs
+++ b/crates/engine/src/cmd/adjust_cmds.rs
@@ -403,6 +403,7 @@ fn shadows_highlights_params(p: &Value) -> ShadowsHighlights {
     }
 }
 
+/// Recorded Lab bounds use native profile matching; ordinary RGB samples keep their existing path.
 fn replace_color(s: &mut Session, p: &Value) -> Result<Value> {
     if let Some(result) = replace_color_range::apply(s, p)? {
         return Ok(result);
diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 3bb6cf312c..8386135d37 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -128,6 +128,7 @@ mod tests {
     use super::*;
     use photocraft_color::PixelFormat;
 
+    /// Work buffers follow explicit selected pixels without cropping implicitly selected coverage.
     #[test]
     fn selected_work_bounds_preserve_implicit_selection_and_clip_explicit_pixels() {
         let content = Rect::new(-100, -100, 100, 100);
diff --git a/crates/engine/src/cmd/atn_cmds/adjustments.rs b/crates/engine/src/cmd/atn_cmds/adjustments.rs
index 80339db65c..b326fb66e6 100644
--- a/crates/engine/src/cmd/atn_cmds/adjustments.rs
+++ b/crates/engine/src/cmd/atn_cmds/adjustments.rs
@@ -343,6 +343,7 @@ fn gradient_map_from(d: &Descriptor) -> Option<Value> {
     Some(out)
 }
 
+/// Write the legacy gradient form without absorbing settings owned by a direct recorded event.
 fn gradient_map_to(p: &Value) -> Option<Descriptor> {
     // A recorded GrMp has its own strict converter. Never fall back to the older
     // event if its origin/settings were changed into an unrepresentable form.
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index f9fb795a84..87b713f3fd 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -474,6 +474,7 @@ fn settings_at_the_value_the_event_plays_still_export() {
 }
 
 #[test]
+/// Each mapped command retains its parameters through its corresponding ATN descriptor.
 fn every_mapped_command_exports_and_imports_back() {
     let cases: Vec<(&str, Value)> = vec![
         ("filter.blur.gaussianBlur", json!({"radius": 3.5})),
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 7678eb99c7..3952ee02d0 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -92,6 +92,7 @@ fn saved(s: &Session) -> AtnItem {
     atn::parse(&bytes).unwrap().actions.remove(0).items.remove(0)
 }
 
+/// Edit a known nested fixture object without replacing its surrounding descriptor.
 fn object<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Descriptor {
     match &mut d.items.iter_mut().find(|(k, _)| k.is(key)).unwrap().1 {
         D::Descriptor(d) => d,
@@ -99,6 +100,7 @@ fn object<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Descriptor {
     }
 }
 
+/// Expose a fixture list so negative cases change only the intended wire setting.
 fn list<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Vec<D> {
     match &mut d.items.iter_mut().find(|(k, _)| k.is(key)).unwrap().1 {
         D::List(l) => l,
@@ -106,6 +108,7 @@ fn list<'a>(d: &'a mut Descriptor, key: &str) -> &'a mut Vec<D> {
     }
 }
 
+/// Locate the first color stop for fractional-color and unsupported-setting controls.
 fn first_stop(d: &mut Descriptor) -> &mut Descriptor {
     match &mut list(object(d, "Grad"), "Clrs")[0] {
         D::Descriptor(d) => d,
@@ -113,6 +116,7 @@ fn first_stop(d: &mut Descriptor) -> &mut Descriptor {
     }
 }
 
+/// Saving retains the measured wire forms, including source colors that hex would quantize.
 #[test]
 fn direct_forms_save_exact_descriptors_including_fractional_rgb() {
     let mut fractional = gradient();
@@ -171,6 +175,7 @@ fn play(s: &mut Session) {
     assert!(report.get("failed").is_none(), "{report}");
 }
 
+/// Execute fractional stops at every depth while preserving unselected samples and Undo.
 #[test]
 fn fractional_gradient_changes_pixels_and_preserves_selection_and_undo() {
     let mut descriptor = gradient();
@@ -227,6 +232,7 @@ fn set_lab_pixels(s: &mut Session) {
     .unwrap();
 }
 
+/// Different box widths must select different pixels even when their midpoint is identical.
 #[test]
 fn lab_boxes_with_the_same_midpoint_have_different_real_effects() {
     // Independent mask anchors: at zero fuzziness a neutral Lab50 pixel is
@@ -254,6 +260,7 @@ fn lab_boxes_with_the_same_midpoint_have_different_real_effects() {
     }
 }
 
+/// Conflicting or invalid Lab settings leave both pixels and history untouched.
 #[test]
 fn invalid_lab_inputs_are_rejected_before_any_edit() {
     let mut s = fixture("rgb", 32);
@@ -287,6 +294,7 @@ fn kept(event: [u8; 4], d: Descriptor) {
     assert_eq!(saved(&s).descriptor, Some(d));
 }
 
+/// Unsupported interpolation, transparency and wire types survive as complete kept steps.
 #[test]
 fn unsupported_gradient_settings_and_wire_forms_remain_kept() {
     let mut midpoint = gradient();
@@ -310,6 +318,7 @@ fn unsupported_gradient_settings_and_wire_forms_remain_kept() {
     assert_eq!(atn_cmds::import(&atn::write(&f).unwrap()).unwrap().unsupported.len(), 1);
 }
 
+/// Invalid recorded boxes stay preserved, and edited or unrepresentable native settings cannot save lossily.
 #[test]
 fn invalid_replace_descriptors_and_lossy_exports_are_refused() {
     let mut model = replace();
@@ -334,6 +343,7 @@ fn invalid_replace_descriptors_and_lossy_exports_are_refused() {
     }
 }
 
+/// Playback respects bounded and implicitly selected masks at every depth, including an offset selection and Undo.
 #[test]
 fn recorded_replace_color_clamps_shifts_and_plays_the_lab_box_at_every_depth() {
     for (depth, inverse) in [8, 16, 32].into_iter().flat_map(|depth| [(depth, false), (depth, true)]) {
@@ -379,6 +389,7 @@ fn recorded_replace_color_clamps_shifts_and_plays_the_lab_box_at_every_depth() {
     }
 }
 
+/// Matching uses original Lab/CMYK channels and tagged RGB rather than display-converted samples.
 #[test]
 fn lab_matching_uses_native_channels_and_the_embedded_rgb_profile() {
     use photocraft_cms::{Builtin, Transform, TransformOptions};
@@ -420,6 +431,7 @@ fn lab_matching_uses_native_channels_and_the_embedded_rgb_profile() {
     }
 }
 
+/// Existing RGB replacement and ordinary gradient export retain their native behavior.
 #[test]
 fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {
     let mut s = fixture("rgb", 32);
@@ -436,6 +448,7 @@ fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {
     assert_eq!(atn::parse(&b).unwrap().actions[0].items[0].event, AtnEvent::Code(*b"GdMp"), "10702 owns the named-event repair");
 }
 
+/// Replacement preserves alpha and refuses locked or profile-incompatible surfaces before editing.
 #[test]
 fn lab_replace_preserves_alpha_and_rejects_locked_or_mismatched_surfaces() {
     let p = json!({"labMinimum":[0,-128,-128],"labMaximum":[100,127,127],"lightness":100});
@@ -466,6 +479,7 @@ fn lab_replace_preserves_alpha_and_rejects_locked_or_mismatched_surfaces() {
     assert_eq!(mismatch.active().unwrap().doc, original);
 }
 
+/// A zero shift must not alter native ink values through an unnecessary RGB separation.
 #[test]
 fn an_unchanged_lab_tone_shift_preserves_native_cmyk_samples() {
     for depth in [8, 16, 32] {

From e3782469910462c88971e63f808bb267732e0aa0 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 15:53:19 -0800
Subject: [PATCH 027/109] Bound Lab Replace Color buffers to stored tiles

---
 .../cmd/adjust_cmds/replace_color_range.rs    | 94 ++++++++++++-------
 .../engine/tests/it/atn_direct_adjustments.rs | 61 ++++++++++++
 2 files changed, 123 insertions(+), 32 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 8386135d37..6977681056 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -82,42 +82,72 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
     s.edit("Replace Color", |doc, _| {
         let selected = doc.selection.clone();
         let surface = crate::commands::paint_surface(doc, id, &Value::Null)?;
-        let rect = edit_bounds(surface.content_bounds(), selected.as_ref());
-        if rect.is_empty() {
-            return Ok(Value::Null);
-        }
-        let raw = surface.read_region(rect);
-        let mut lab = vec![[0.0, 0.0, 0.0, 1.0]; raw.len() / format.channels()];
-        transform.convert_f32(&raw, format.channels(), lab.as_flattened_mut(), 4, true);
-        for p in &mut lab {
-            let value = [p[0] * 100.0, p[1] * 255.0 - 128.0, p[2] * 255.0 - 128.0];
-            let [l, a, b] = if grid { selection::quantize_lab8(value) } else { value };
-            *p = [l, a, b, p[3]];
-        }
-        let mask = selection::color_range_lab(&lab, rect.width() as usize, &range, fuzz, grid, None);
-        let mut rgba = raw.chunks_exact(format.channels()).map(|p| photocraft_raster::to_rgba(&format, p)).collect::<Vec<_>>();
-        let original_rgba = rgba.clone();
-        tone::replace_color_masked(&mut rgba, &mask, h, sat, l);
-        let mut output = crate::pixels::mix_through_selection(&format, rect, &original_rgba, &rgba, selected.as_ref());
-        // Unmatched native Lab/CMYK values must not take an incidental RGB roundtrip.
-        let width = rect.width() as usize;
-        let row_len = width * format.channels();
-        let mut selection_row = vec![1.0; width];
-        for (y, ((out, original), mask)) in output.chunks_exact_mut(row_len).zip(raw.chunks_exact(row_len)).zip(mask.chunks_exact(width)).enumerate() {
-            if let Some(selected) = selected.as_ref() {
-                selected.sample_row_strided(rect.y0.saturating_add(y as i32), rect.x0, 1, 0, &mut selection_row);
+        let bounds = edit_bounds(surface.content_bounds(), selected.as_ref());
+        // Transparent gaps cannot match. Visit stored tiles instead of the possibly
+        // enormous rectangle between two distant pixels.
+        let stored = if format.alpha && surface.default_pixel().last().is_some_and(|a| a.is_nan() || *a <= 0.0) {
+            let mut tiles = crate::allocation::capacity(surface.tiles().count(), "Replace Color tile coordinates")?;
+            tiles.extend(surface.tiles().map(|(tile, _)| *tile));
+            Some(tiles)
+        } else {
+            None
+        };
+        // Matching and tone changes are pointwise. Tile-sized work also bounds buffers
+        // for full-layer edits, without imposing a new image-size limit.
+        let mut process_tile = |tile: photocraft_geom::TileCoord| -> Result<()> {
+            let rect = tile.rect().intersect(&bounds);
+            if rect.is_empty() {
+                return Ok(());
             }
-            for (x, (((out, original), coverage), selected)) in
-                out.chunks_exact_mut(format.channels()).zip(original.chunks_exact(format.channels())).zip(mask).zip(&selection_row).enumerate()
-            {
-                let index = y * width + x;
-                let unchanged = rgba.get(index).zip(original_rgba.get(index)).is_some_and(|(a, b)| a == b);
-                if *coverage <= 0.0 || *selected <= 0.0 || unchanged {
-                    out.copy_from_slice(original);
+            let mut raw = crate::allocation::read_region(surface, rect, "Replace Color")?;
+            let mut lab = crate::allocation::filled(raw.len() / format.channels(), [0.0, 0.0, 0.0, 1.0], "Replace Color")?;
+            transform.convert_f32(&raw, format.channels(), lab.as_flattened_mut(), 4, true);
+            let width = rect.width() as usize;
+            let mut selection_row = crate::allocation::filled(width, 1.0, "Replace Color")?;
+            let mut changed = false;
+            for (y, (row, lab_row)) in raw.chunks_exact_mut(width * format.channels()).zip(lab.chunks_exact(width)).enumerate() {
+                if let Some(selected) = selected.as_ref() {
+                    selected.sample_row_strided(rect.y0.saturating_add(y as i32), rect.x0, 1, 0, &mut selection_row);
+                }
+                for ((pixel, sample), selected) in row.chunks_exact_mut(format.channels()).zip(lab_row).zip(&selection_row) {
+                    if sample[3].is_nan() || sample[3] <= 0.0 || *selected <= 0.0 {
+                        continue;
+                    }
+                    let value = [sample[0] * 100.0, sample[1] * 255.0 - 128.0, sample[2] * 255.0 - 128.0];
+                    let coverage = if grid {
+                        selection::lab_range_coverage_8bit(selection::quantize_lab8(value), &range, fuzz)
+                    } else {
+                        selection::lab_range_coverage(value, &range, fuzz)
+                    };
+                    if coverage <= 0.0 {
+                        continue;
+                    }
+                    let original = photocraft_raster::to_rgba(&format, pixel);
+                    let mut edited = [original];
+                    tone::replace_color_masked(&mut edited, &[coverage], h, sat, l);
+                    // Unchanged native samples must not take an incidental RGB roundtrip.
+                    if edited[0] == original {
+                        continue;
+                    }
+                    let mixed = std::array::from_fn(|c| original[c] * (1.0 - selected) + edited[0][c] * selected);
+                    photocraft_raster::from_rgba_into(&format, mixed, pixel);
+                    changed = true;
                 }
             }
+            if changed {
+                surface.try_write_region(rect, &raw).map_err(|e| crate::allocation::error("Replace Color", &e.to_string()))?;
+            }
+            Ok(())
+        };
+        if let Some(tiles) = stored {
+            for tile in tiles {
+                process_tile(tile)?;
+            }
+        } else {
+            for tile in bounds.tiles() {
+                process_tile(tile)?;
+            }
         }
-        surface.write_region(rect, &output);
         Ok(Value::Null)
     })
     .map(Some)
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 3952ee02d0..37a3ab0e62 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -431,6 +431,67 @@ fn lab_matching_uses_native_channels_and_the_embedded_rgb_profile() {
     }
 }
 
+/// Full and selected edits agree across tile edges, including the final partial tiles and Undo.
+#[test]
+fn lab_replace_crosses_tile_edges_without_changing_unselected_native_pixels() {
+    let area = photocraft_doc::Rect::new(0, 0, 260, 132);
+    let window = photocraft_doc::Rect::new(127, 127, 130, 130);
+    for depth in [8, 16, 32] {
+        for selected in ["none", "window", "outside"] {
+            let mut s = fixture("lab", depth);
+            s.edit("Known Lab tiles", |doc, active| {
+                doc.size = photocraft_doc::Size::new(260, 132);
+                doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().fill_rect(area, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+                if selected != "none" {
+                    let default = if selected == "outside" { 1.0 } else { 0.0 };
+                    let mut mask = photocraft_raster::Surface::with_default(photocraft_doc::PixelFormat::GRAY8, &[default]);
+                    mask.fill_rect(window, &[1.0 - default]);
+                    doc.selection = Some(mask);
+                }
+                Ok(())
+            })
+            .unwrap();
+            let before = s.active().unwrap().doc.clone();
+            let original = raw(&s);
+            s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+            let after = raw(&s);
+            for (i, (pixel, original)) in after.chunks_exact(4).zip(original.chunks_exact(4)).enumerate() {
+                let inside = (127..130).contains(&(i % 260)) && (127..130).contains(&(i / 260));
+                let changed = selected == "none" || (selected == "window") == inside;
+                if changed {
+                    assert!(pixel[0] > 0.99, "{depth}/{selected} pixel {i}: {pixel:?}");
+                } else {
+                    assert_eq!(pixel, original, "{depth}/{selected} pixel {i}");
+                }
+                assert_eq!(pixel[3], original[3]);
+            }
+            assert!(s.undo());
+            assert_eq!(s.active().unwrap().doc, before);
+        }
+    }
+}
+
+/// Sparse off-canvas content must not materialize or scan the large transparent gap between its tiles.
+#[test]
+fn lab_replace_visits_only_stored_tiles_when_the_default_is_transparent() {
+    let mut s = fixture("lab", 32);
+    let far = photocraft_doc::Rect::new(100_000, 100_000, 100_001, 100_001);
+    s.edit("Distant Lab pixel", |doc, active| {
+        doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().fill_rect(far, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+        Ok(())
+    })
+    .unwrap();
+    let before = s.active().unwrap().doc.clone();
+    let layer = s.active().unwrap().active_layer.unwrap();
+    let count = before.layer(layer).unwrap().surface().unwrap().tiles().count();
+    s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+    let surface = s.active().unwrap().doc.layer(layer).unwrap().surface().unwrap();
+    assert!(surface.read_region(far)[0] > 0.99);
+    assert_eq!(surface.tiles().count(), count);
+    assert!(s.undo());
+    assert_eq!(s.active().unwrap().doc, before);
+}
+
 /// Existing RGB replacement and ordinary gradient export retain their native behavior.
 #[test]
 fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {

From 6152cffe4e010f0afd4209dda114661535527bf2 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 15:56:39 -0800
Subject: [PATCH 028/109] Include opaque default pixels in Lab Replace Color

---
 .../cmd/adjust_cmds/replace_color_range.rs    |  9 +++--
 .../engine/tests/it/atn_direct_adjustments.rs | 35 +++++++++++++++++++
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 6977681056..1a2896f8bf 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -80,12 +80,17 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
         return Ok(Some(Value::Null));
     }
     s.edit("Replace Color", |doc, _| {
+        let canvas = doc.bounds();
         let selected = doc.selection.clone();
         let surface = crate::commands::paint_surface(doc, id, &Value::Null)?;
-        let bounds = edit_bounds(surface.content_bounds(), selected.as_ref());
+        let transparent_default = format.alpha && surface.default_pixel().last().is_some_and(|a| a.is_nan() || *a <= 0.0);
+        let content = surface.content_bounds();
+        // A nontransparent default is visible across the canvas even without stored tiles.
+        let extent = if transparent_default { content } else { content.union(&canvas) };
+        let bounds = edit_bounds(extent, selected.as_ref());
         // Transparent gaps cannot match. Visit stored tiles instead of the possibly
         // enormous rectangle between two distant pixels.
-        let stored = if format.alpha && surface.default_pixel().last().is_some_and(|a| a.is_nan() || *a <= 0.0) {
+        let stored = if transparent_default {
             let mut tiles = crate::allocation::capacity(surface.tiles().count(), "Replace Color tile coordinates")?;
             tiles.extend(surface.tiles().map(|(tile, _)| *tile));
             Some(tiles)
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 37a3ab0e62..92cc246bc8 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -492,6 +492,41 @@ fn lab_replace_visits_only_stored_tiles_when_the_default_is_transparent() {
     assert_eq!(s.active().unwrap().doc, before);
 }
 
+/// Opaque defaults remain visible when the surface has no tiles or only a small exception.
+#[test]
+fn lab_replace_includes_visible_default_pixels_with_and_without_alpha() {
+    for depth in [8, 16, 32] {
+        for (alpha, exception) in [(false, false), (false, true), (true, false), (true, true)] {
+            let mut s = fixture("lab", depth);
+            s.edit("Opaque default Lab", |doc, active| {
+                let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+                let format = photocraft_doc::PixelFormat { alpha, ..surface.format() };
+                let channels = format.channels();
+                *surface = photocraft_raster::Surface::with_default(format, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
+                if exception {
+                    surface.fill_rect(photocraft_doc::Rect::new(1, 0, 2, 1), &[0.25, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
+                } else {
+                    assert!(surface.content_bounds().is_empty());
+                }
+                Ok(())
+            })
+            .unwrap();
+            let before = s.active().unwrap().doc.clone();
+            let original = raw(&s);
+            s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+            for (i, (pixel, original)) in raw(&s).chunks_exact(3 + usize::from(alpha)).zip(original.chunks_exact(3 + usize::from(alpha))).enumerate() {
+                if exception && i == 1 {
+                    assert_eq!(pixel, original);
+                } else {
+                    assert!(pixel[0] > 0.99, "{depth}/{alpha}/{exception} pixel {i}: {pixel:?}");
+                }
+            }
+            assert!(s.undo());
+            assert_eq!(s.active().unwrap().doc, before);
+        }
+    }
+}
+
 /// Existing RGB replacement and ordinary gradient export retain their native behavior.
 #[test]
 fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {

From d82f32db36ba4db76e77d6c59a269b3485b2ca16 Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Mon, 2 Nov 2026 01:01:07 +0100
Subject: [PATCH 029/109] docs(atn): Artboard from Group guides and
 changeBackground measured; editArtboardEvent

Guide ids are session metadata that playback ignores; changeBackground 1 or
absent applies the background type and colour, any other value gives white.
Background types 1..4 = white, black, transparent, other. The recorded step
carries the last used background. Properties panel background changes record
editArtboardEvent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/atn.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/atn.md b/docs/atn.md
index 61c2403a19..0327969095 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -298,7 +298,7 @@ layer reference, `Ordn.Trgt`); mapping them needs only the event name.
 | `placedLayerConvertToLinked` | Layer > Smart Objects > Convert to Linked | `null`: target layer; `Usng`: path of the file written |
 | `placedLayerRelinkToFile` | Layer > Smart Objects > Relink to File | `null`: path; `LyrI`: session layer id |
 | `placedLayerReplaceContents` | Layer > Smart Objects > Replace Contents | `null`: path; `LyrI`: session layer id |
-| `artboardFromLayerGroupEvent` | Layer > New > Artboard from Group | `null` target; `artboard` (object: `guideIDs` list, `artboardPresetName` text, `Clr ` RGB background colour, `artboardBackgroundType` long, 1 = white); `changeBackground` long |
+| `artboardFromLayerGroupEvent` | Layer > New > Artboard from Group | `null` target; `artboard` (object: `guideIDs` list, `artboardPresetName` text, `Clr ` RGB background colour, `artboardBackgroundType` long: 1 white, 2 black, 3 transparent, 4 other = `Clr `); `changeBackground` long. See *Artboard from Group: guides and background* below. |
 | `shapeBlur` | Filter > Blur > Shape Blur | `Rds ` radius in pixels (factory 10); the shape itself comes from the dialog |
 | Make `contentLayer` with `Usng` = reference to `textLayer` `Ordn.Trgt` | Type > Convert to Shape (recorded as Make, not as `convertToShape`) | `null`: class `contentLayer`; `Usng`: the type layer |
 
@@ -311,6 +311,7 @@ layer reference, `Ordn.Trgt`); mapping them needs only the event name.
 | Layer > New > Frame from Layers | Make, `null` = class `framedGroupSection`, `From` = layer **by name**, `layerSectionStart`, `layerSectionEnd` long, `Nm  ` text | the dialog also shows width and height, which are not recorded |
 | Layer > New > Artboard from Layers | Make, `null` = class `artboardSection`, `From` = layer target, `layerSectionStart`, `layerSectionEnd`, `Nm  ` | |
 | Layer > New > Artboard | Make, `null` = class `artboardSection`, `layerSectionStart`, `layerSectionEnd`, `Nm  `, `artboardRect` (`Top `, `Left`, `Btom`, `Rght` doubles, pixels) | |
+| Properties panel > Artboard Background Color (Artboard selected) | `editArtboardEvent` | `null` target; `artboard` (object: `artboardRect` `Top `/`Left`/`Btom`/`Rght` pixels, `guideIDs` list, `artboardPresetName` text, `Clr `, `artboardBackgroundType` 1..4 as above); `changeSizes` long (8 when only the background changed), `changeBackground` 1. `Clr ` is only meaningful with type 4: with types 1..3 it holds the previously used colour |
 | Layer > Smart Objects > Stack Mode > mode | `applyImageStackPluginRenderer`: `imageStackPlugin` **class** with the mode's code, `Nm  ` text = the menu name (localised, except "Entropy") | codes: Range `rang`, Entropy `entr`, Kurtosis `kurt`, Maximum `maxx`, Median `medn`, Minimum `minn`, Mean `avrg`, Skewness `skew`, Standard Deviation `stdv`, Summation `summ`, Variance `vari` |
 | Layer > Smart Objects > Stack Mode > None | `imageStackConvertSmartObject` | none |
 | Layer > Video Layers > New Blank Video Layer, Insert Blank Frame, Delete Frame, Show / Hide Altered Video | `addBlankVideoLayer`, `insertBlankFrame`, `deleteFrame`, `showAlteredVideo` / `hideAlteredVideo` | none |
@@ -346,6 +347,20 @@ layer reference, `Ordn.Trgt`); mapping them needs only the event name.
 **Not recorded:** importing or applying inside Image > Variables > Data Sets (only the separate menu
 commands record).
 
+**Artboard from Group: guides and background** (measured 2026-11-02, script runs and a recording through the menu):
+
+- **Recorded form:** the menu item opens no dialog. The step always has `guideIDs` empty, `artboardPresetName` "", `changeBackground` 1, and the
+  background type and colour **last used** for an artboard (the Properties panel choice is sticky: after picking Black for one artboard, the
+  next Artboard from Group records type 2 and makes a black artboard). Guides in the document do not change the recorded step.
+- **`guideIDs`:** session metadata, not a playback input. Guide ids are a counter for the whole application session (a new document's
+  guides got 5, 6, 7 after an earlier one's 2, 3, 4). Playing the step with the document's own guide ids, an unknown id (99999) or an
+  empty list gives the same result: no error, the guides stay document guides (`kind` document), and the new artboard's `guideIDs` is empty.
+  An implementation can ignore the list on playback and write `[]`.
+- **`changeBackground`:** 1 or absent applies `artboardBackgroundType` and `Clr `. Any other value (0, 2, 3, -1, 7 tried) ignores both and
+  makes a white artboard (type 1, `Clr ` 255/255/255), and the step's result then has no `changeBackground` key.
+  `artboardBackgroundType` absent with `changeBackground` 1 gives type 1 (white).
+- The artboard takes the group's bounds; `Clr ` is stored on the artboard as given even when the type is 1..3.
+
 ## Measured through dialogs and recordings
 
 Measured on 2026-11-01 in two ways: by running the event with its dialog and pressing OK (the reference

From 545e6f21dbcea3c414d6efeb614800e0151f9629 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 16:08:18 -0800
Subject: [PATCH 030/109] Exercise the actual raster tile boundaries in Lab
 replacement

---
 crates/engine/tests/it/atn_direct_adjustments.rs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 92cc246bc8..a893c63433 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -434,13 +434,15 @@ fn lab_matching_uses_native_channels_and_the_embedded_rgb_profile() {
 /// Full and selected edits agree across tile edges, including the final partial tiles and Undo.
 #[test]
 fn lab_replace_crosses_tile_edges_without_changing_unselected_native_pixels() {
-    let area = photocraft_doc::Rect::new(0, 0, 260, 132);
-    let window = photocraft_doc::Rect::new(127, 127, 130, 130);
+    let tile = photocraft_geom::TILE_SIZE;
+    let area = photocraft_doc::Rect::new(0, 0, tile + 4, tile + 3);
+    let window = photocraft_doc::Rect::new(tile - 1, tile - 1, tile + 2, tile + 2);
+    let width = area.width() as usize;
     for depth in [8, 16, 32] {
         for selected in ["none", "window", "outside"] {
             let mut s = fixture("lab", depth);
             s.edit("Known Lab tiles", |doc, active| {
-                doc.size = photocraft_doc::Size::new(260, 132);
+                doc.size = area.size();
                 doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().fill_rect(area, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
                 if selected != "none" {
                     let default = if selected == "outside" { 1.0 } else { 0.0 };
@@ -456,7 +458,7 @@ fn lab_replace_crosses_tile_edges_without_changing_unselected_native_pixels() {
             s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
             let after = raw(&s);
             for (i, (pixel, original)) in after.chunks_exact(4).zip(original.chunks_exact(4)).enumerate() {
-                let inside = (127..130).contains(&(i % 260)) && (127..130).contains(&(i / 260));
+                let inside = window.contains((i % width) as i32, (i / width) as i32);
                 let changed = selected == "none" || (selected == "window") == inside;
                 if changed {
                     assert!(pixel[0] > 0.99, "{depth}/{selected} pixel {i}: {pixel:?}");

From ecd7b2df5536ce07dae33d695d61848f5c856cd5 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 16:18:10 -0800
Subject: [PATCH 031/109] Initialize the merged ATN encoding field in the test
 fixture

---
 crates/engine/tests/it/atn_direct_adjustments.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index a893c63433..47e0e38912 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -60,6 +60,7 @@ fn bytes(event: [u8; 4], descriptor: Descriptor) -> Vec<u8> {
             ..Default::default()
         }],
         warnings: vec![],
+        ..Default::default()
     })
     .unwrap()
 }

From 9ce240b10413c31a54aa17d40d6d0eb2fd1d5b4f Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 16:29:11 -0800
Subject: [PATCH 032/109] Bound Lab replacement work for sparse opaque surfaces

---
 .../cmd/adjust_cmds/replace_color_range.rs    | 136 +++++++++++-----
 crates/engine/src/pixels.rs                   |   5 +
 .../engine/tests/it/atn_direct_adjustments.rs | 153 +++++++++++++-----
 3 files changed, 215 insertions(+), 79 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 1a2896f8bf..3bb88ea790 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -1,8 +1,8 @@
 //! Recorded Replace Color samples are a Lab box, not a single RGB colour.
 use photocraft_algo::{selection, tone};
 use photocraft_cms::{Builtin, TransformOptions};
-use photocraft_doc::SampleType;
-use photocraft_geom::Rect;
+use photocraft_doc::{PixelFormat, SampleType};
+use photocraft_geom::{Rect, TileCoord};
 use photocraft_raster::Surface;
 use serde_json::Value;
 
@@ -30,6 +30,47 @@ fn bound(p: &Value, key: &str) -> Result<[f64; 3]> {
     Ok(result)
 }
 
+/// Apply the same Lab match, tone shift and selection mix to stored and implicit pixels.
+fn replace_sample(format: &PixelFormat, pixel: &mut [f32], sample: &[f32; 4], range: &selection::LabRange, fuzz: f32, shift: [f32; 3], selected: f32) -> bool {
+    if sample[3].is_nan() || sample[3] <= 0.0 || selected <= 0.0 {
+        return false;
+    }
+    let value = [sample[0] * 100.0, sample[1] * 255.0 - 128.0, sample[2] * 255.0 - 128.0];
+    let coverage = if format.sample == SampleType::U8 {
+        selection::lab_range_coverage_8bit(selection::quantize_lab8(value), range, fuzz)
+    } else {
+        selection::lab_range_coverage(value, range, fuzz)
+    };
+    if coverage <= 0.0 {
+        return false;
+    }
+    let original = photocraft_raster::to_rgba(format, pixel);
+    let mut edited = [original];
+    tone::replace_color_masked(&mut edited, &[coverage], shift[0], shift[1], shift[2]);
+    // Unchanged native samples must not take an incidental RGB roundtrip.
+    if edited[0] == original {
+        return false;
+    }
+    let mixed = std::array::from_fn(|c| original[c] * (1.0 - selected) + edited[0][c] * selected);
+    photocraft_raster::from_rgba_into(format, mixed, pixel);
+    true
+}
+
+/// A zero-default selection or an unchanged source default needs only stored tiles.
+/// Otherwise retain the full edit rectangle, subject to the existing adjustment storage budget.
+fn work_tiles(surface: &Surface, selected: Option<&Surface>, bounds: Rect, default_changes: bool) -> Result<Option<Vec<TileCoord>>> {
+    let sparse = selected.filter(|mask| mask.default_pixel().first() == Some(&0.0)).or_else(|| (!default_changes).then_some(surface));
+    if let Some(sparse) = sparse {
+        let coords = || sparse.tiles().map(|(tile, _)| *tile).filter(|tile| !tile.rect().intersect(&bounds).is_empty());
+        let mut tiles = crate::allocation::capacity(coords().count(), "Replace Color tile coordinates")?;
+        tiles.extend(coords());
+        return Ok(Some(tiles));
+    }
+    let stored = surface.tiles().filter(|(tile, _)| !tile.rect().intersect(&bounds).is_empty()).count();
+    crate::pixels::check_adjustment_tile_budget(bounds, stored, &surface.format()).map_err(EngineError::Other)?;
+    Ok(None)
+}
+
 /// Apply explicit recorded bounds; `None` leaves the legacy RGB/sample path alone.
 /// Matching converts original surface channels through their document profile,
 /// before the existing RGBA tone shift can clip or change their colour space.
@@ -88,18 +129,14 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
         // A nontransparent default is visible across the canvas even without stored tiles.
         let extent = if transparent_default { content } else { content.union(&canvas) };
         let bounds = edit_bounds(extent, selected.as_ref());
-        // Transparent gaps cannot match. Visit stored tiles instead of the possibly
-        // enormous rectangle between two distant pixels.
-        let stored = if transparent_default {
-            let mut tiles = crate::allocation::capacity(surface.tiles().count(), "Replace Color tile coordinates")?;
-            tiles.extend(surface.tiles().map(|(tile, _)| *tile));
-            Some(tiles)
-        } else {
-            None
-        };
-        // Matching and tone changes are pointwise. Tile-sized work also bounds buffers
-        // for full-layer edits, without imposing a new image-size limit.
-        let mut process_tile = |tile: photocraft_geom::TileCoord| -> Result<()> {
+        let mut default = surface.default_pixel();
+        let mut default_lab = [[0.0, 0.0, 0.0, 1.0]];
+        transform.convert_f32(&default, format.channels(), default_lab.as_flattened_mut(), 4, true);
+        let default_selected = selected.as_ref().map_or(1.0, |mask| mask.default_pixel()[0]);
+        let default_changes = replace_sample(&format, &mut default, &default_lab[0], &range, fuzz, [h, sat, l], default_selected);
+        let tiles = work_tiles(surface, selected.as_ref(), bounds, default_changes)?;
+        // Matching and tone changes are pointwise, so pixel work stays tile-sized.
+        let mut process_tile = |tile: TileCoord| -> Result<()> {
             let rect = tile.rect().intersect(&bounds);
             if rect.is_empty() {
                 return Ok(());
@@ -115,28 +152,7 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
                     selected.sample_row_strided(rect.y0.saturating_add(y as i32), rect.x0, 1, 0, &mut selection_row);
                 }
                 for ((pixel, sample), selected) in row.chunks_exact_mut(format.channels()).zip(lab_row).zip(&selection_row) {
-                    if sample[3].is_nan() || sample[3] <= 0.0 || *selected <= 0.0 {
-                        continue;
-                    }
-                    let value = [sample[0] * 100.0, sample[1] * 255.0 - 128.0, sample[2] * 255.0 - 128.0];
-                    let coverage = if grid {
-                        selection::lab_range_coverage_8bit(selection::quantize_lab8(value), &range, fuzz)
-                    } else {
-                        selection::lab_range_coverage(value, &range, fuzz)
-                    };
-                    if coverage <= 0.0 {
-                        continue;
-                    }
-                    let original = photocraft_raster::to_rgba(&format, pixel);
-                    let mut edited = [original];
-                    tone::replace_color_masked(&mut edited, &[coverage], h, sat, l);
-                    // Unchanged native samples must not take an incidental RGB roundtrip.
-                    if edited[0] == original {
-                        continue;
-                    }
-                    let mixed = std::array::from_fn(|c| original[c] * (1.0 - selected) + edited[0][c] * selected);
-                    photocraft_raster::from_rgba_into(&format, mixed, pixel);
-                    changed = true;
+                    changed |= replace_sample(&format, pixel, sample, &range, fuzz, [h, sat, l], *selected);
                 }
             }
             if changed {
@@ -144,7 +160,7 @@ pub(super) fn apply(s: &mut Session, p: &Value) -> Result<Option<Value>> {
             }
             Ok(())
         };
-        if let Some(tiles) = stored {
+        if let Some(tiles) = tiles {
             for tile in tiles {
                 process_tile(tile)?;
             }
@@ -178,4 +194,50 @@ mod tests {
             assert_eq!(edit_bounds(content, Some(&mask)), content, "stored holes do not bound selected pixels");
         }
     }
+
+    /// The work list follows stored source or selection tiles rather than their distant bounds.
+    #[test]
+    fn sparse_work_tiles_follow_pixels_that_can_change() {
+        let near = Rect::new(0, 0, 1, 1);
+        let far = Rect::new(100_000, 100_000, 100_001, 100_001);
+        let bounds = near.union(&far);
+        for format in [PixelFormat::RGB8, PixelFormat::RGBA8] {
+            let mut surface = Surface::with_default(format, &[1.0; 4][..format.channels()]);
+            surface.fill_rect(far, &[0.0; 4][..format.channels()]);
+            assert_eq!(work_tiles(&surface, None, bounds, false).unwrap(), Some(vec![TileCoord::containing(far.x0, far.y0)]));
+            let mut mask = Surface::new(PixelFormat::GRAY8);
+            mask.fill_rect(near, &[1.0]);
+            mask.fill_rect(far, &[1.0]);
+            assert_eq!(
+                work_tiles(&surface, Some(&mask), bounds, true).unwrap(),
+                Some(vec![TileCoord::containing(0, 0), TileCoord::containing(far.x0, far.y0)])
+            );
+            assert!(work_tiles(&surface, None, near, true).unwrap().is_none(), "a small default-only area remains editable");
+        }
+    }
+
+    /// A matching opaque default cannot allocate gap tiles beyond the existing adjustment budget.
+    #[test]
+    fn opaque_gap_budget_refuses_before_pixel_allocation_or_edit() {
+        let mut s = Session::new();
+        s.execute("file.new", serde_json::json!({"width":4,"height":2,"mode":"lab","depth":32,"background":"transparent"})).unwrap();
+        s.edit("Distant opaque exception", |doc, active| {
+            let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+            *surface = Surface::with_default(surface.format(), &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+            surface.fill_rect(Rect::new(100_000, 100_000, 100_001, 100_001), &[0.25, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+            Ok(())
+        })
+        .unwrap();
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        crate::allocation::fail_next_for_test();
+        let result = s.execute(CMD, serde_json::json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100}));
+        // Drain the probe even on failure so another test cannot inherit it. A skipped probe
+        // proves that the resource check ran before any fallible tile-buffer allocation.
+        let probe_unused = crate::allocation::capacity::<u8>(0, "allocation probe").is_err();
+        assert!(result.as_ref().is_err_and(|e| e.to_string().contains("too large an area")), "{result:?}");
+        assert!(probe_unused);
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
 }
diff --git a/crates/engine/src/pixels.rs b/crates/engine/src/pixels.rs
index 906f0b23c6..f65f0c8635 100644
--- a/crates/engine/src/pixels.rs
+++ b/crates/engine/src/pixels.rs
@@ -83,6 +83,11 @@ fn tile_rects(r: Rect) -> impl Iterator<Item = Rect> {
 
 const TOO_SPARSE: &str = "the adjustment would have to fill too large an area around the pixels the layer holds";
 
+/// Refuse adjustments that would materialize too much previously unstored pixel data.
+pub(crate) fn check_adjustment_tile_budget(area: Rect, stored: usize, format: &photocraft_color::PixelFormat) -> Result<(), String> {
+    if unstored_bytes(area, stored as u64, format) > MAX_UNSTORED_BYTES { Err(TOO_SPARSE.into()) } else { Ok(()) }
+}
+
 /// Apply an adjustment destructively to a surface, weighted by an optional selection.
 /// Applies `adj` to a surface (any colour model and depth, via straight RGBA) through the
 /// selection; `mode` is the document's, for the tone transfer (e.g. Exposure in Grayscale).
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 47e0e38912..51cd050d11 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -474,62 +474,131 @@ fn lab_replace_crosses_tile_edges_without_changing_unselected_native_pixels() {
     }
 }
 
-/// Sparse off-canvas content must not materialize or scan the large transparent gap between its tiles.
+/// Matching stored pixels change without materializing gaps whose default does not change.
 #[test]
-fn lab_replace_visits_only_stored_tiles_when_the_default_is_transparent() {
-    let mut s = fixture("lab", 32);
-    let far = photocraft_doc::Rect::new(100_000, 100_000, 100_001, 100_001);
-    s.edit("Distant Lab pixel", |doc, active| {
-        doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().fill_rect(far, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
-        Ok(())
-    })
-    .unwrap();
-    let before = s.active().unwrap().doc.clone();
-    let layer = s.active().unwrap().active_layer.unwrap();
-    let count = before.layer(layer).unwrap().surface().unwrap().tiles().count();
-    s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
-    let surface = s.active().unwrap().doc.layer(layer).unwrap().surface().unwrap();
-    assert!(surface.read_region(far)[0] > 0.99);
-    assert_eq!(surface.tiles().count(), count);
-    assert!(s.undo());
-    assert_eq!(s.active().unwrap().doc, before);
+fn lab_replace_sparse_pixels_preserve_unstored_gaps() {
+    let tile = photocraft_geom::TILE_SIZE;
+    let far = photocraft_doc::Rect::new(4 * tile, 4 * tile, 4 * tile + 1, 4 * tile + 1);
+    let second = far.translate(2 * tile, 0);
+    let gap = far.translate(tile, 0);
+    for (alpha, opacity) in [(true, 0.0), (true, 1.0), (false, 1.0)] {
+        let mut s = fixture("lab", 32);
+        s.edit("Two distant Lab pixels", |doc, active| {
+            let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+            let format = photocraft_doc::PixelFormat { alpha, ..surface.format() };
+            let channels = format.channels();
+            *surface = photocraft_raster::Surface::with_default(format, &[0.25, 128.0 / 255.0, 128.0 / 255.0, opacity][..channels]);
+            for rect in [far, second] {
+                surface.fill_rect(rect, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
+            }
+            Ok(())
+        })
+        .unwrap();
+        let before = s.active().unwrap().doc.clone();
+        let layer = s.active().unwrap().active_layer.unwrap();
+        let original = before.layer(layer).unwrap().surface().unwrap();
+        assert_eq!(original.tile_count(), 2);
+        s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+        let surface = s.active().unwrap().doc.layer(layer).unwrap().surface().unwrap();
+        for rect in [far, second] {
+            assert!(surface.read_region(rect)[0] > 0.99);
+        }
+        assert_eq!(surface.read_region(gap), original.read_region(gap));
+        assert_eq!(surface.default_pixel(), original.default_pixel());
+        assert_eq!(surface.tile_count(), 2);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
 }
 
 /// Opaque defaults remain visible when the surface has no tiles or only a small exception.
 #[test]
 fn lab_replace_includes_visible_default_pixels_with_and_without_alpha() {
+    let tile = photocraft_geom::TILE_SIZE;
+    let far = photocraft_doc::Rect::new(2 * tile + 1, 2 * tile + 1, 2 * tile + 2, 2 * tile + 2);
     for depth in [8, 16, 32] {
-        for (alpha, exception) in [(false, false), (false, true), (true, false), (true, true)] {
-            let mut s = fixture("lab", depth);
-            s.edit("Opaque default Lab", |doc, active| {
-                let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
-                let format = photocraft_doc::PixelFormat { alpha, ..surface.format() };
-                let channels = format.channels();
-                *surface = photocraft_raster::Surface::with_default(format, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
-                if exception {
-                    surface.fill_rect(photocraft_doc::Rect::new(1, 0, 2, 1), &[0.25, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
-                } else {
-                    assert!(surface.content_bounds().is_empty());
+        for alpha in [false, true] {
+            for exception in [None, Some(photocraft_doc::Rect::new(1, 0, 2, 1)), Some(far)] {
+                let mut s = fixture("lab", depth);
+                s.edit("Opaque default Lab", |doc, active| {
+                    let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+                    let format = photocraft_doc::PixelFormat { alpha, ..surface.format() };
+                    let channels = format.channels();
+                    *surface = photocraft_raster::Surface::with_default(format, &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
+                    if let Some(rect) = exception {
+                        surface.fill_rect(rect, &[0.25, 128.0 / 255.0, 128.0 / 255.0, 1.0][..channels]);
+                    } else {
+                        assert!(surface.content_bounds().is_empty());
+                    }
+                    Ok(())
+                })
+                .unwrap();
+                let before = s.active().unwrap().doc.clone();
+                let original = raw(&s);
+                s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+                for (i, (pixel, original)) in raw(&s).chunks_exact(3 + usize::from(alpha)).zip(original.chunks_exact(3 + usize::from(alpha))).enumerate() {
+                    if exception == Some(photocraft_doc::Rect::new(1, 0, 2, 1)) && i == 1 {
+                        assert_eq!(pixel, original);
+                    } else {
+                        assert!(pixel[0] > 0.99, "{depth}/{alpha}/{exception:?} pixel {i}: {pixel:?}");
+                    }
                 }
-                Ok(())
-            })
-            .unwrap();
-            let before = s.active().unwrap().doc.clone();
-            let original = raw(&s);
-            s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
-            for (i, (pixel, original)) in raw(&s).chunks_exact(3 + usize::from(alpha)).zip(original.chunks_exact(3 + usize::from(alpha))).enumerate() {
-                if exception && i == 1 {
-                    assert_eq!(pixel, original);
-                } else {
-                    assert!(pixel[0] > 0.99, "{depth}/{alpha}/{exception} pixel {i}: {pixel:?}");
+                if exception == Some(far) {
+                    let layer = s.active().unwrap().active_layer.unwrap();
+                    let surface = s.active().unwrap().doc.layer(layer).unwrap().surface().unwrap();
+                    assert!(surface.read_region(far.translate(-tile, 0))[0] > 0.99, "off-canvas defaults inside the edit extent change too");
+                    assert_eq!(surface.read_region(far), before.layer(layer).unwrap().surface().unwrap().read_region(far));
+                    assert_eq!(surface.read_region(far.translate(2, 2)), surface.default_pixel(), "pixels outside the extent stay unchanged");
                 }
+                assert!(s.undo());
+                assert_eq!(s.active().unwrap().doc, before);
             }
-            assert!(s.undo());
-            assert_eq!(s.active().unwrap().doc, before);
         }
     }
 }
 
+/// Selection islands and holes retain their coverage over unstored opaque pixels.
+#[test]
+fn lab_replace_selection_controls_opaque_gap_pixels() {
+    let tile = photocraft_geom::TILE_SIZE;
+    let far = photocraft_doc::Rect::new(2 * tile, 2 * tile, 2 * tile + 1, 2 * tile + 1);
+    let gap = far.translate(-tile, -tile);
+    for implicit in [false, true] {
+        let mut s = fixture("lab", 32);
+        s.edit("Selected opaque gap", |doc, active| {
+            let surface = doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap();
+            *surface = photocraft_raster::Surface::with_default(surface.format(), &[0.5, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+            surface.fill_rect(far, &[0.25, 128.0 / 255.0, 128.0 / 255.0, 1.0]);
+            let coverage = if implicit { 1.0 } else { 0.0 };
+            let mut mask = photocraft_raster::Surface::with_default(photocraft_doc::PixelFormat::GRAY8, &[coverage]);
+            mask.fill_rect(gap, &[1.0 - coverage]);
+            doc.selection = Some(mask);
+            Ok(())
+        })
+        .unwrap();
+        let before = s.active().unwrap().doc.clone();
+        let layer = s.active().unwrap().active_layer.unwrap();
+        let original = before.layer(layer).unwrap().surface().unwrap();
+        s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
+        let surface = s.active().unwrap().doc.layer(layer).unwrap().surface().unwrap();
+        let canvas_pixel = photocraft_doc::Rect::new(0, 0, 1, 1);
+        for (rect, changed) in [(gap, !implicit), (canvas_pixel, implicit)] {
+            if changed {
+                assert!(surface.read_region(rect)[0] > 0.99);
+            } else {
+                assert_eq!(surface.read_region(rect), original.read_region(rect));
+            }
+        }
+        assert_eq!(surface.read_region(far), original.read_region(far));
+        assert_eq!(surface.default_pixel(), original.default_pixel());
+        if !implicit {
+            assert_eq!(surface.tile_count(), 2, "only the selected gap tile is added");
+        }
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
 /// Existing RGB replacement and ordinary gradient export retain their native behavior.
 #[test]
 fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {

From 2c1a83e54240ea57540c87eeffd62bad6c2237d6 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 16:36:54 -0800
Subject: [PATCH 033/109] Construct both alpha layouts explicitly in the
 work-plan test

---
 crates/engine/src/cmd/adjust_cmds/replace_color_range.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index 3bb88ea790..b5eccf0cc7 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -201,7 +201,8 @@ mod tests {
         let near = Rect::new(0, 0, 1, 1);
         let far = Rect::new(100_000, 100_000, 100_001, 100_001);
         let bounds = near.union(&far);
-        for format in [PixelFormat::RGB8, PixelFormat::RGBA8] {
+        for alpha in [false, true] {
+            let format = PixelFormat { alpha, ..PixelFormat::RGBA8 };
             let mut surface = Surface::with_default(format, &[1.0; 4][..format.channels()]);
             surface.fill_rect(far, &[0.0; 4][..format.channels()]);
             assert_eq!(work_tiles(&surface, None, bounds, false).unwrap(), Some(vec![TileCoord::containing(far.x0, far.y0)]));

From ed71465b8907690ad2a88ad6e8d3eef3a60a41fe Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 16:58:20 -0800
Subject: [PATCH 034/109] Apply measured Artboard background settings without
 resizing

---
 crates/engine/src/cmd/artboard_cmds.rs        |  20 +-
 crates/engine/src/cmd/atn_cmds/events.rs      |   3 +-
 .../engine/src/cmd/atn_cmds/steps_artboard.rs | 139 ++++++++++----
 crates/engine/src/cmd/atn_cmds/tests.rs       |   6 +-
 crates/engine/tests/it/atn_newer_events.rs    | 173 ++++++++++++++----
 docs/atn.md                                   |  29 +--
 docs/development.md                           |   6 +
 7 files changed, 276 insertions(+), 100 deletions(-)

diff --git a/crates/engine/src/cmd/artboard_cmds.rs b/crates/engine/src/cmd/artboard_cmds.rs
index 89e7a15d00..e8821925e4 100644
--- a/crates/engine/src/cmd/artboard_cmds.rs
+++ b/crates/engine/src/cmd/artboard_cmds.rs
@@ -301,7 +301,7 @@ fn new_artboard(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({"layer": id.0, "rect": [rect.x0, rect.y0, rect.width(), rect.height()]}))
 }
 
-/// Convert a plain group without resizing its content bounds; refuse unresolved recorded guide associations before editing.
+/// Convert a plain group at its content bounds; recorded guide IDs are ignored session metadata.
 fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "layer.new.artboardFromGroup";
     let d = s.active().ok_or(EngineError::NoDocument)?;
@@ -310,19 +310,17 @@ fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
         None => String::new(),
         Some(value) => value.as_str().ok_or_else(|| bad(cmd, "preset must be text"))?.to_string(),
     };
-    if p.get("changeBackground").is_some_and(|value| value != &Value::Bool(true)) {
-        return Err(bad(cmd, "only an explicit true background-change flag is supported"));
-    }
+    let apply_background = match p.get("changeBackground") {
+        None | Some(Value::Bool(true)) => true,
+        Some(value) => value.as_i64().and_then(|n| i32::try_from(n).ok()).ok_or_else(|| bad(cmd, "changeBackground must be an integer"))? == 1,
+    };
     if let Some(guides) = p.get("guideIDs") {
-        if !guides.as_array().is_some_and(Vec::is_empty) {
-            return Err(bad(cmd, "recorded guide associations are not supported"));
-        }
-        if !d.doc.guides.horizontal.is_empty() || !d.doc.guides.vertical.is_empty() {
-            return Err(bad(cmd, "an explicit empty guide association requires a document without guides"));
+        if !guides.as_array().is_some_and(|ids| ids.iter().all(|id| id.as_i64().is_some_and(|n| i32::try_from(n).is_ok()))) {
+            return Err(bad(cmd, "guideIDs must be a list of integers"));
         }
     }
     let canvas = d.doc.bounds();
-    let background = background_param(p, cmd)?.unwrap_or_default();
+    let background = if apply_background { background_param(p, cmd)?.unwrap_or_default() } else { ArtboardBackground::White };
     let rect = s.edit("Artboard from Group", |doc, active| {
         if !doc.layers.iter().any(|t| t.id == id && t.is_group() && t.artboard().is_none()) {
             return Err(EngineError::Other("artboards are made from a top-level layer group".into()));
@@ -720,7 +718,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "layer.new.artboardFromGroup",
             "Artboard from Group…",
             &["Layer", "New"],
-            r##"{"layer":id? (a top-level group; default active),"background":…?,"color":[r,g,b]|"#rrggbb"?,"preset":str? (tag only; does not resize),"guideIDs":[]? (recorded empty association; requires no document guides),"changeBackground":true? (recorded apply flag; other values refused)} → {layer, rect}"##,
+            r##"{"layer":id? (a top-level group; default active),"background":…?,"color":[r,g,b]|"#rrggbb"?,"preset":str? (tag only; does not resize),"guideIDs":[int]? (ignored recording metadata),"changeBackground":int? (1 or absent applies background/color; other integers give white; legacy true = 1)} → {layer, rect}"##,
             has_plain_group,
             artboard_from_group
         ),
diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 2cf8017606..60b518fe1c 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -2,7 +2,7 @@ const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
 use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, path_text, path_value, ref_class, target_ref};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
-use super::steps_artboard::{artboard_from, artboard_to};
+use super::steps_artboard::{artboard_edit_from, artboard_edit_to, artboard_from, artboard_to};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
     crop_from, crop_to, export_from, export_to, image_size_from, image_size_to, merge_visible_from, merge_visible_to, open_from, open_to, paste_from, paste_to,
@@ -500,6 +500,7 @@ pub(super) const EVENTS: &[Event] = &[
         from: artboard_from,
         to: artboard_to,
     },
+    Event { code: "", name: "editArtboardEvent", label: "Edit Artboard", ids: &["layer.artboard.set"], from: artboard_edit_from, to: artboard_edit_to },
     Event { code: "", name: "linkSelectedLayers", label: "Link Layers", ids: &["layer.linkLayers"], from: |d| link_from(d, true), to: |_, p| link_to(p, true) },
     Event {
         code: "",
diff --git a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
index 8d2964d95a..43115b3b1c 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
@@ -1,45 +1,37 @@
-//! Strict Artboard from Group forms whose settings the existing native model can apply.
+//! Measured Artboard conversion and background-only Properties edits.
 
 use super::descriptors::{desc, get_num, get_obj, get_text, target_ref, text};
 use super::fields::{Mapped, none, step};
 use super::{D, Descriptor, Value, json};
 
-const COMMAND: &str = "layer.new.artboardFromGroup";
+const FROM_GROUP: &str = "layer.new.artboardFromGroup";
+const EDIT: &str = "layer.artboard.set";
 
-/// Import the current-target form or the verified empty-guide settings form, keeping other forms whole.
-pub(super) fn artboard_from(d: &Descriptor) -> Mapped {
-    let unsupported = Mapped::Unsupported { harmless: false };
-    if d.items == desc("null").with("null", target_ref("Lyr ")).items {
-        return none(COMMAND);
-    }
-    let Some(board) = get_obj(d, "artboard") else { return unsupported };
-    let Some(color) = get_obj(board, "Clr ") else { return unsupported };
-    let Some(preset) = get_text(board, "artboardPresetName") else { return unsupported };
+/// Keep recorded colors and ignored guide IDs, including an omitted background type.
+fn settings_from(board: &Descriptor, preset_key: &str) -> Option<Value> {
+    let color = get_obj(board, "Clr ")?;
+    let preset = get_text(board, "artboardPresetName")?;
     let background = match board.get("artboardBackgroundType") {
-        Some(D::Integer(1)) => "white",
+        None | Some(D::Integer(1)) => "white",
         Some(D::Integer(2)) => "black",
         Some(D::Integer(3)) => "transparent",
         Some(D::Integer(4)) => "custom",
-        _ => return unsupported,
+        _ => return None,
     };
-    let rgb: Option<Vec<f64>> = ["Rd  ", "Grn ", "Bl  "].iter().map(|key| get_num(color, key).map(|n| n / 255.0)).collect();
-    let Some(rgb) = rgb else { return unsupported };
-    let p = json!({"background": background, "color": rgb, "preset": preset, "guideIDs": [], "changeBackground": true});
-    // Reconstruction checks every ordered key, nested class, value type and the evidenced flag.
-    if artboard_to(COMMAND, &p).is_some_and(|expected| expected.items == d.items) { step(COMMAND, p) } else { unsupported }
+    let Some(D::List(guides)) = board.get("guideIDs") else { return None };
+    let guides: Vec<i32> = guides.iter().map(|v| if let D::Integer(n) = v { Some(*n) } else { None }).collect::<Option<_>>()?;
+    let rgb: Vec<f64> = ["Rd  ", "Grn ", "Bl  "].iter().map(|key| get_num(color, key).map(|n| n / 255.0)).collect::<Option<_>>()?;
+    let mut p = json!({"background": background, "color": rgb, "guideIDs": guides});
+    p[preset_key] = preset.into();
+    if board.get("artboardBackgroundType").is_none() {
+        p["backgroundTypeOmitted"] = true.into();
+    }
+    Some(p)
 }
 
-/// Export only current-target steps or complete, representable empty-guide settings without quantizing RGB.
-pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
-    let p = p.as_object()?;
-    let d = desc("null").with("null", target_ref("Lyr "));
-    if p.is_empty() {
-        return Some(d);
-    }
-    if p.len() != 5 || p.get("changeBackground") != Some(&Value::Bool(true)) || !p.get("guideIDs")?.as_array()?.is_empty() {
-        return None;
-    }
-    let preset = p.get("preset")?.as_str()?;
+/// Rebuild only settings whose native meaning still agrees with the saved wire form.
+fn settings_to(p: &Value, preset_key: &str) -> Option<Descriptor> {
+    let preset = p.get(preset_key)?.as_str()?;
     let background = match p.get("background")?.as_str()? {
         "white" => 1,
         "black" => 2,
@@ -47,6 +39,7 @@ pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
         "custom" => 4,
         _ => return None,
     };
+    let guides = p.get("guideIDs")?.as_array()?.iter().map(|v| Some(D::Integer(i32::try_from(v.as_i64()?).ok()?))).collect::<Option<Vec<_>>>()?;
     let rgb = p.get("color")?.as_array()?;
     if rgb.len() != 3 {
         return None;
@@ -56,10 +49,86 @@ pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
         return None;
     }
     let color = ["Rd  ", "Grn ", "Bl  "].into_iter().zip(rgb).fold(desc("RGBC"), |d, (key, n)| d.with(key, D::Double(n * 255.0)));
-    let board = desc("artboard")
-        .with("guideIDs", D::List(vec![]))
-        .with("artboardPresetName", text(preset))
-        .with("Clr ", D::Descriptor(color))
-        .with("artboardBackgroundType", D::Integer(background));
-    Some(d.with("artboard", D::Descriptor(board)).with("changeBackground", D::Integer(1)))
+    let board = desc("artboard").with("guideIDs", D::List(guides)).with("artboardPresetName", text(preset)).with("Clr ", D::Descriptor(color));
+    match p.get("backgroundTypeOmitted") {
+        None => Some(board.with("artboardBackgroundType", D::Integer(background))),
+        Some(Value::Bool(true)) if background == 1 => Some(board),
+        _ => None,
+    }
+}
+
+/// Import target-only conversion or complete recorded settings, preserving flag absence and values.
+pub(super) fn artboard_from(d: &Descriptor) -> Mapped {
+    let unsupported = Mapped::Unsupported { harmless: false };
+    if d.items == desc("null").with("null", target_ref("Lyr ")).items {
+        return none(FROM_GROUP);
+    }
+    let Some(mut p) = get_obj(d, "artboard").and_then(|b| settings_from(b, "preset")) else { return unsupported };
+    match d.get("changeBackground") {
+        None => {}
+        Some(D::Integer(n)) => p["changeBackground"] = (*n).into(),
+        _ => return unsupported,
+    }
+    if artboard_to(FROM_GROUP, &p).is_some_and(|expected| expected.items == d.items) { step(FROM_GROUP, p) } else { unsupported }
+}
+
+/// Save complete recorded conversion settings; unknown native options must not disappear.
+pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
+    let fields = p.as_object()?;
+    let d = desc("null").with("null", target_ref("Lyr "));
+    if fields.is_empty() {
+        return Some(d);
+    }
+    if fields.keys().any(|k| !["background", "color", "preset", "guideIDs", "changeBackground", "backgroundTypeOmitted"].contains(&k.as_str())) {
+        return None;
+    }
+    let d = d.with("artboard", D::Descriptor(settings_to(p, "preset")?));
+    match p.get("changeBackground") {
+        None => Some(d),
+        // Older native action files used true for the recorded integer 1.
+        Some(Value::Bool(true)) => Some(d.with("changeBackground", D::Integer(1))),
+        Some(value) => Some(d.with("changeBackground", D::Integer(i32::try_from(value.as_i64()?).ok()?))),
+    }
+}
+
+/// Background-only edits retain recorded geometry as metadata, never as native resize parameters.
+pub(super) fn artboard_edit_from(d: &Descriptor) -> Mapped {
+    let unsupported = Mapped::Unsupported { harmless: false };
+    let Some(board) = get_obj(d, "artboard") else { return unsupported };
+    let Some(rect) = get_obj(board, "artboardRect") else { return unsupported };
+    let Some(mut p) = settings_from(board, "recordedPreset") else { return unsupported };
+    let Some(edges) = ["Top ", "Left", "Btom", "Rght"].iter().map(|key| get_num(rect, key)).collect::<Option<Vec<_>>>() else { return unsupported };
+    p["recordedRect"] = json!(edges);
+    p["changeSizes"] = 8.into();
+    p["changeBackground"] = 1.into();
+    if artboard_edit_to(EDIT, &p).is_some_and(|expected| expected.items == d.items) { step(EDIT, p) } else { unsupported }
+}
+
+/// Export only the measured background-edit flags and exact recorded rectangle, without quantization.
+pub(super) fn artboard_edit_to(_: &str, p: &Value) -> Option<Descriptor> {
+    let fields = p.as_object()?;
+    if fields.keys().any(|k| {
+        !["background", "color", "recordedPreset", "guideIDs", "recordedRect", "changeSizes", "changeBackground", "backgroundTypeOmitted"].contains(&k.as_str())
+    }) || p.get("changeSizes")?.as_i64()? != 8
+        || p.get("changeBackground")?.as_i64()? != 1
+    {
+        return None;
+    }
+    let edges = p.get("recordedRect")?.as_array()?;
+    if edges.len() != 4 {
+        return None;
+    }
+    let rect = ["Top ", "Left", "Btom", "Rght"]
+        .into_iter()
+        .zip(edges)
+        .try_fold(desc("classFloatRect"), |d, (key, value)| Some(d.with(key, D::Double(value.as_f64().filter(|v| v.is_finite())?))))?;
+    let mut board = desc("artboard").with("artboardRect", D::Descriptor(rect));
+    board.items.extend(settings_to(p, "recordedPreset")?.items);
+    Some(
+        desc("null")
+            .with("null", target_ref("Lyr "))
+            .with("artboard", D::Descriptor(board))
+            .with("changeSizes", D::Integer(8))
+            .with("changeBackground", D::Integer(1)),
+    )
 }
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 71b0edc15d..598f1c2d24 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -576,7 +576,11 @@ fn every_mapped_command_exports_and_imports_back() {
         ("file.automate.cropAndStraightenPhotos", json!({})),
         ("file.automate.cropAndStraightenPhotos", json!({"_atnNoTarget": true})),
         ("layer.new.artboardFromGroup", json!({})),
-        ("layer.new.artboardFromGroup", json!({"background":"white","color":[1,1,1],"preset":"","guideIDs":[],"changeBackground":true})),
+        ("layer.new.artboardFromGroup", json!({"background":"white","color":[1,1,1],"preset":"","guideIDs":[],"changeBackground":1})),
+        (
+            "layer.artboard.set",
+            json!({"background":"custom","color":[0.25,0.5,0.75],"recordedPreset":"","guideIDs":[],"recordedRect":[2,2,6,6],"changeSizes":8,"changeBackground":1}),
+        ),
         ("layer.new.layerViaCopy", json!({})),
         ("layer.newFillLayer.solidColor", json!({"color": "#336699"})),
         ("layer.newAdjustmentLayer.hueSaturation", json!({})),
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index ed63f3d333..816935cce8 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -64,6 +64,7 @@ fn file(event: &str, descriptor: Descriptor) -> Vec<u8> {
             ..Default::default()
         }],
         warnings: vec![],
+        ..Default::default()
     })
     .unwrap()
 }
@@ -442,40 +443,56 @@ fn artboard_fixture() -> Session {
 
 /// The reference's ordered settings keys, with fractional RGB that must not be rounded to hex.
 fn artboard_descriptor(background: i32, guides: Vec<D>, flag: D) -> Descriptor {
+    Descriptor::new("null").with("null", target()).with("artboard", D::Descriptor(artboard_settings(Some(background), guides))).with("changeBackground", flag)
+}
+
+/// Background types 1..3 still record the last custom RGB value; absent type means white.
+fn artboard_settings(background: Option<i32>, guides: Vec<D>) -> Descriptor {
     let color = Descriptor::new("RGBC").with("Rd  ", D::Double(63.75)).with("Grn ", D::Double(127.5)).with("Bl  ", D::Double(191.25));
     let board = Descriptor::new("artboard")
         .with("guideIDs", D::List(guides))
         .with("artboardPresetName", D::Text(UnicodeString::new_nul("iPhone 14")))
-        .with("Clr ", D::Descriptor(color))
-        .with("artboardBackgroundType", D::Integer(background));
-    Descriptor::new("null").with("null", target()).with("artboard", D::Descriptor(board)).with("changeBackground", flag)
+        .with("Clr ", D::Descriptor(color));
+    match background {
+        Some(n) => board.with("artboardBackgroundType", D::Integer(n)),
+        None => board,
+    }
 }
 
 /// Conversion preserves the group's geometry/content while applying every admitted setting and Undo.
 #[test]
-fn artboard_empty_guide_settings_roundtrip_apply_background_and_preset_without_resizing() {
+fn artboard_recorded_flags_and_guides_roundtrip_without_resizing() {
     for (background, expected) in [(1, [1.0, 1.0, 1.0, 1.0]), (2, [0.0, 0.0, 0.0, 1.0]), (3, [0.0; 4]), (4, [0.25, 0.5, 0.75, 1.0])] {
-        let mut s = artboard_fixture();
-        let before = s.active().unwrap().doc.clone();
-        let id = s.active().unwrap().active_layer.unwrap();
-        let d = artboard_descriptor(background, vec![], D::Integer(1));
-        assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"], json!([]));
-        assert_eq!(s.actions.list[0].steps[0].0, "layer.new.artboardFromGroup");
-        assert_eq!(s.actions.list[0].steps[0].1["color"], json!([0.25, 0.5, 0.75]));
-        assert_eq!(saved_item(&mut s).descriptor, Some(d));
-        play(&mut s);
-        let doc = &s.active().unwrap().doc;
-        let board = doc.layer(id).unwrap().artboard().unwrap();
-        assert_eq!(board.rect, photocraft_doc::Rect::new(2, 2, 6, 6), "preset is a tag, not a request to resize the group");
-        assert_eq!(board.preset, "iPhone 14");
-        assert_eq!(doc.size, before.size);
-        assert_eq!(doc.layer(id).unwrap().children(), before.layer(id).unwrap().children());
-        let pixel = photocraft_compose::render(doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0];
-        for (actual, expected) in pixel.into_iter().zip(expected) {
-            assert!((actual - expected).abs() < 0.005, "background {background}: {pixel:?}");
+        for flag in [None, Some(0), Some(1), Some(2), Some(3), Some(-1), Some(7)] {
+            let mut s = artboard_fixture();
+            Arc::make_mut(&mut s.active_mut().unwrap().doc).guides.horizontal.push(3.0);
+            Arc::make_mut(&mut s.active_mut().unwrap().doc).guides.vertical.push(4.0);
+            let before = s.active().unwrap().doc.clone();
+            let id = s.active().unwrap().active_layer.unwrap();
+            let mut d = artboard_descriptor(background, vec![D::Integer(2), D::Integer(99999)], D::Integer(flag.unwrap_or(1)));
+            if flag.is_none() {
+                d.items.pop();
+            }
+            assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"], json!([]));
+            assert_eq!(s.actions.list[0].steps[0].0, "layer.new.artboardFromGroup");
+            assert_eq!(s.actions.list[0].steps[0].1["color"], json!([0.25, 0.5, 0.75]));
+            assert_eq!(saved_item(&mut s).descriptor, Some(d));
+            play(&mut s);
+            let doc = &s.active().unwrap().doc;
+            let board = doc.layer(id).unwrap().artboard().unwrap();
+            assert_eq!(board.rect, photocraft_doc::Rect::new(2, 2, 6, 6), "preset is a tag, not a request to resize the group");
+            assert_eq!(board.preset, "iPhone 14");
+            assert_eq!(doc.size, before.size);
+            assert_eq!(doc.layer(id).unwrap().children(), before.layer(id).unwrap().children());
+            assert_eq!(doc.guides, before.guides);
+            let pixel = photocraft_compose::render(doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0];
+            let applied = flag.is_none_or(|n| n == 1);
+            for (actual, expected) in pixel.into_iter().zip(if applied { expected } else { [1.0; 4] }) {
+                assert!((actual - expected).abs() < 0.005, "background {background}, flag {flag:?}: {pixel:?}");
+            }
+            assert!(s.undo());
+            assert_eq!(s.active().unwrap().doc, before);
         }
-        assert!(s.undo());
-        assert_eq!(s.active().unwrap().doc, before);
     }
 }
 
@@ -496,11 +513,9 @@ fn artboard_target_only_form_keeps_existing_native_group_behavior() {
 
 /// Unproved settings remain byte-preserving kept steps and cannot partially edit the document.
 #[test]
-fn artboard_unproven_associations_flags_and_extra_settings_stay_whole() {
+fn artboard_unmeasured_types_and_extra_settings_stay_whole() {
     for d in [
-        artboard_descriptor(1, vec![D::Integer(7)], D::Integer(1)),
-        artboard_descriptor(1, vec![], D::Integer(0)),
-        artboard_descriptor(1, vec![], D::Integer(2)),
+        artboard_descriptor(1, vec![D::Double(7.0)], D::Integer(1)),
         artboard_descriptor(1, vec![], D::Boolean(true)),
         artboard_descriptor(5, vec![], D::Integer(1)),
         artboard_descriptor(1, vec![], D::Integer(1)).with("extra", D::Boolean(true)),
@@ -523,27 +538,107 @@ fn artboard_unproven_associations_flags_and_extra_settings_stay_whole() {
     }
 }
 
-/// An explicit empty association cannot silently acquire the document's spatially inferred guides.
+/// Omitted type means white rather than the color-only native call's custom background.
 #[test]
-fn artboard_empty_association_refuses_existing_guides_before_editing() {
+fn artboard_omitted_type_defaults_to_white_and_invalid_native_settings_are_atomic() {
     let mut s = artboard_fixture();
-    Arc::make_mut(&mut s.active_mut().unwrap().doc).guides.horizontal.push(3.0);
     let before = s.active().unwrap().doc.clone();
-    let history = s.active().unwrap().history.past_len();
-    assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", artboard_descriptor(4, vec![], D::Integer(1))))["unsupported"], json!([]));
-    let report = s.execute("actions.play", json!({"action":"A","set":"Links"})).unwrap();
-    assert_eq!(report["ran"], 0, "{report}");
-    assert_eq!(report["failed"]["id"], "layer.new.artboardFromGroup");
-    assert!(report["failed"]["error"].as_str().unwrap().contains("without guides"));
+    let d =
+        Descriptor::new("null").with("null", target()).with("artboard", D::Descriptor(artboard_settings(None, vec![]))).with("changeBackground", D::Integer(1));
+    assert_eq!(load(&mut s, &file("artboardFromLayerGroupEvent", d.clone()))["unsupported"], json!([]));
+    assert_eq!(saved_item(&mut s).descriptor, Some(d));
+    let mut changed = s.actions.list[0].steps[0].1.clone();
+    changed["background"] = "black".into();
+    assert!(atn_cmds::export("Links", &[&Action::new("A", vec![("layer.new.artboardFromGroup".into(), changed)])], &[], false).is_err());
+    play(&mut s);
+    assert_eq!(photocraft_compose::render(&s.active().unwrap().doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0], [1.0; 4]);
+    assert!(s.undo());
     assert_eq!(s.active().unwrap().doc, before);
-    assert_eq!(s.active().unwrap().history.past_len(), history);
-    for p in [json!({"guideIDs":[7]}), json!({"guideIDs":false}), json!({"changeBackground":false}), json!({"preset":7})] {
+    let history = s.active().unwrap().history.past_len();
+    for p in [
+        json!({"guideIDs":[7.5]}),
+        json!({"guideIDs":false}),
+        json!({"changeBackground":false}),
+        json!({"changeBackground":2147483648i64}),
+        json!({"preset":7}),
+    ] {
         assert!(s.execute("layer.new.artboardFromGroup", p).is_err());
         assert_eq!(s.active().unwrap().doc, before);
         assert_eq!(s.active().unwrap().history.past_len(), history);
     }
 }
 
+/// Recorded geometry deliberately differs from the target: flag 8 changes only its background.
+fn artboard_edit_descriptor(background: i32, change_sizes: i32) -> Descriptor {
+    let rect = Descriptor::new("classFloatRect")
+        .with("Top ", D::Double(40.5))
+        .with("Left", D::Double(60.25))
+        .with("Btom", D::Double(340.5))
+        .with("Rght", D::Double(260.25));
+    let mut board = Descriptor::new("artboard").with("artboardRect", D::Descriptor(rect));
+    board.items.extend(artboard_settings(Some(background), vec![D::Integer(99999)]).items);
+    Descriptor::new("null")
+        .with("null", target())
+        .with("artboard", D::Descriptor(board))
+        .with("changeSizes", D::Integer(change_sizes))
+        .with("changeBackground", D::Integer(1))
+}
+
+/// Background edits preserve all wire fields, target geometry, children and guides, with one Undo.
+#[test]
+fn artboard_background_edit_roundtrips_without_replaying_recorded_geometry() {
+    for (kind, expected) in [(1, [1.0; 4]), (2, [0.0, 0.0, 0.0, 1.0]), (3, [0.0; 4]), (4, [0.25, 0.5, 0.75, 1.0])] {
+        let mut s = artboard_fixture();
+        s.execute("layer.new.artboardFromGroup", json!({})).unwrap();
+        Arc::make_mut(&mut s.active_mut().unwrap().doc).guides.horizontal.push(3.0);
+        let before = s.active().unwrap().doc.clone();
+        let id = s.active().unwrap().active_layer.unwrap();
+        let history = s.active().unwrap().history.past_len();
+        let d = artboard_edit_descriptor(kind, 8);
+        assert_eq!(load(&mut s, &file("editArtboardEvent", d.clone()))["unsupported"], json!([]));
+        assert_eq!(s.actions.list[0].steps[0].0, "layer.artboard.set");
+        assert_eq!(saved_item(&mut s).descriptor, Some(d));
+        play(&mut s);
+        let doc = &s.active().unwrap().doc;
+        let board = doc.layer(id).unwrap().artboard().unwrap();
+        assert_eq!(board.rect, before.layer(id).unwrap().artboard().unwrap().rect);
+        assert_eq!(board.preset, before.layer(id).unwrap().artboard().unwrap().preset);
+        assert_eq!(doc.layer(id).unwrap().children(), before.layer(id).unwrap().children());
+        assert_eq!(doc.size, before.size);
+        assert_eq!(doc.guides, before.guides);
+        let pixel = photocraft_compose::render(doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0];
+        for (actual, expected) in pixel.into_iter().zip(expected) {
+            assert!((actual - expected).abs() < 0.005, "{kind}: {pixel:?}");
+        }
+        assert_eq!(s.active().unwrap().history.past_len(), history + 1);
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
+/// Unmeasured geometry modes remain whole; edited native resize options cannot be silently omitted.
+#[test]
+fn artboard_edit_refuses_unmeasured_modes_and_lossy_native_exports() {
+    let mut s = artboard_fixture();
+    for d in [artboard_edit_descriptor(1, 4), artboard_edit_descriptor(5, 8), artboard_edit_descriptor(1, 8).with("extra", D::Integer(1))] {
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        assert_eq!(load(&mut s, &file("editArtboardEvent", d.clone()))["unsupported"].as_array().unwrap().len(), 1);
+        assert_eq!(saved_item(&mut s).descriptor, Some(d));
+        let result = s.execute("actions.play", json!({"set":"Links","action":"A"})).unwrap();
+        assert_eq!(result["ran"], 0);
+        assert_eq!(s.active().unwrap().doc, before);
+        assert_eq!(s.active().unwrap().history.past_len(), history);
+    }
+    load(&mut s, &file("editArtboardEvent", artboard_edit_descriptor(4, 8)));
+    let params = s.actions.list[0].steps[0].1.clone();
+    for (key, value) in [("rect", json!([0, 0, 100, 100])), ("preset", json!("iPhone 14")), ("changeSizes", json!(4)), ("changeBackground", json!(0))] {
+        let mut edited = params.clone();
+        edited[key] = value;
+        assert!(atn_cmds::export("Links", &[&Action::new("A", vec![("layer.artboard.set".into(), edited)])], &[], false).is_err());
+    }
+}
+
 #[test]
 fn reverse_linked_selection_and_clear_style_events_do_their_edits() {
     for explicit in [false, true] {
diff --git a/docs/atn.md b/docs/atn.md
index c08a76ac5a..00e2852689 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -160,23 +160,26 @@ the reference application.
 | (string ID only) | placedLayerRelinkToFile | Relink to File | `layer.smartObjects.relinkToFile` |
 | (string ID only) | placedLayerReplaceContents | Replace Contents | `layer.smartObjects.replaceContents` |
 | (string ID only) | shapeBlur | Shape Blur (radius-only form) | `filter.blur.shapeBlur` |
-| (string ID only) | artboardFromLayerGroupEvent | Artboard from Group (limited forms below) | `layer.new.artboardFromGroup` |
+| (string ID only) | artboardFromLayerGroupEvent | Artboard from Group | `layer.new.artboardFromGroup` |
+| (string ID only) | editArtboardEvent | Artboard background color (flags 8/1) | `layer.artboard.set` |
 
 ### Newer event mapping boundaries
 
-Twenty-two of the 23 requested forms in the two **Measured** tables under
-[Newer events](#newer-events-string-id-only) are fully mapped. Artboard from Group
-has an intermediate mapping for the canonical current-layer target alone, or a
-complete settings object with empty `guideIDs` and integer `changeBackground: 1`.
-The latter requires a document without guides, so the existing spatial guide
-export cannot manufacture an association. The preset is retained as a tag without
-resizing the group; RGB background channels retain fractional values. Only forms
-that reconstruct exactly are admitted. Unrepresented native options refuse export.
+The 23 requested forms in the two **Measured** tables under
+[Newer events](#newer-events-string-id-only) are mapped. Artboard from Group
+retains the current-layer target, preset tag, fractional RGB, background type
+and integer `changeBackground`, including absence. A flag of 1 or absence applies
+the background; other integers give white. An omitted type defaults to white.
+Recorded guide IDs are preserved on save and ignored on playback, as measured
+in [the guide/background reference below](#newer-events-string-id-only).
+Existing document guides remain unchanged. The preset does not resize the group.
 
-Nonempty guide associations and other flag values remain complete kept steps.
-The Artboard row is still unfinished: [Adobe documents guide IDs as object identities](https://developer.adobe.com/photoshop/uxp/2022/ps-reference/classes/guide),
-separate from list positions, and the current native model has no corresponding
-identity/ownership binding. No guide ID is discarded or treated as an array index.
+The additional `editArtboardEvent` maps background-only changes with `changeSizes`
+8 and `changeBackground` 1. Its rectangle and preset remain recording metadata:
+they do not move or resize the target artboard. Colors remain in the saved step
+even for white, black or transparent backgrounds. Other flags, extra settings,
+unknown targets and forms that cannot reconstruct exactly remain whole kept
+steps. Native geometry edits without a matching wire form refuse export.
 
 The sixteen target-only events accept an empty descriptor or the current-layer
 `null` reference (`Lyr `/`Ordn.Trgt`). Save retains which form was imported.
diff --git a/docs/development.md b/docs/development.md
index 277d20b954..16a92b1312 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -631,6 +631,12 @@ PhotoCraft equivalent.
 Events outside the table load as `actions.photoshopStep` steps that keep the descriptor
 verbatim (so Save Actions writes them back) and fail at playback with the step's Photoshop name.
 
+Artboard from Group action settings follow [the measured guide/background behavior](atn.md#newer-events-string-id-only):
+guide IDs are ignored session metadata, 1 or absent `changeBackground` applies the
+background, and other integer flags give white. The group's bounds are retained.
+Background-only `editArtboardEvent` uses the existing Artboard edit command; its
+recorded rectangle/preset are retained for saving, without resizing the target.
+
 `crates/psd/tests/it/atn_contract.rs` checks the parser's public API against four small,
 independently encoded fixtures in `crates/psd/tests/fixtures/atn/` (provenance and checksums in
 its README): `cargo test -p photocraft-psd --test it atn_contract::`.

From c06d7d1e34821c2d51c3befb412adba50b4f96ba Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 17:00:10 -0800
Subject: [PATCH 035/109] Simplify recorded guide validation

---
 crates/engine/src/cmd/artboard_cmds.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/cmd/artboard_cmds.rs b/crates/engine/src/cmd/artboard_cmds.rs
index e8821925e4..c3ba0dd2dd 100644
--- a/crates/engine/src/cmd/artboard_cmds.rs
+++ b/crates/engine/src/cmd/artboard_cmds.rs
@@ -314,10 +314,10 @@ fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
         None | Some(Value::Bool(true)) => true,
         Some(value) => value.as_i64().and_then(|n| i32::try_from(n).ok()).ok_or_else(|| bad(cmd, "changeBackground must be an integer"))? == 1,
     };
-    if let Some(guides) = p.get("guideIDs") {
-        if !guides.as_array().is_some_and(|ids| ids.iter().all(|id| id.as_i64().is_some_and(|n| i32::try_from(n).is_ok()))) {
-            return Err(bad(cmd, "guideIDs must be a list of integers"));
-        }
+    if let Some(guides) = p.get("guideIDs")
+        && !guides.as_array().is_some_and(|ids| ids.iter().all(|id| id.as_i64().is_some_and(|n| i32::try_from(n).is_ok())))
+    {
+        return Err(bad(cmd, "guideIDs must be a list of integers"));
     }
     let canvas = d.doc.bounds();
     let background = if apply_background { background_param(p, cmd)?.unwrap_or_default() } else { ArtboardBackground::White };

From f4e066439b291f8c5e8fd708d20fd10f2251c035 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 17:26:45 -0800
Subject: [PATCH 036/109] Preserve Replace Color alpha during fractional
 selection mixing

---
 .../cmd/adjust_cmds/replace_color_range.rs    |  3 +-
 .../engine/tests/it/atn_direct_adjustments.rs | 28 ++++++++++++++++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
index b5eccf0cc7..574610523c 100644
--- a/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
+++ b/crates/engine/src/cmd/adjust_cmds/replace_color_range.rs
@@ -51,7 +51,8 @@ fn replace_sample(format: &PixelFormat, pixel: &mut [f32], sample: &[f32; 4], ra
     if edited[0] == original {
         return false;
     }
-    let mixed = std::array::from_fn(|c| original[c] * (1.0 - selected) + edited[0][c] * selected);
+    let mut mixed = std::array::from_fn(|c| original[c] * (1.0 - selected) + edited[0][c] * selected);
+    mixed[3] = original[3];
     photocraft_raster::from_rgba_into(format, mixed, pixel);
     true
 }
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 51cd050d11..dd26c6491a 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -144,7 +144,9 @@ fn direct_forms_save_exact_descriptors_including_fractional_rgb() {
     changed.items[5].1 = D::Integer(-20);
     for descriptor in [replace(), changed] {
         let s = load(*b"RplC", descriptor.clone(), "image.adjustments.replaceColor");
-        assert_eq!(saved(&s).descriptor, Some(descriptor));
+        let item = saved(&s);
+        assert_eq!(item.event, AtnEvent::Code(*b"RplC"));
+        assert_eq!(item.descriptor, Some(descriptor));
     }
 }
 
@@ -647,6 +649,30 @@ fn lab_replace_preserves_alpha_and_rejects_locked_or_mismatched_surfaces() {
     assert_eq!(mismatch.active().unwrap().doc, original);
 }
 
+/// Fractional selection mixing changes RGB while preserving each F32 alpha bit exactly.
+#[test]
+fn lab_replace_fractional_selection_preserves_f32_alpha_bits() {
+    for coverage in [53.0 / 255.0, 127.0 / 255.0] {
+        let mut s = fixture("rgb", 32);
+        s.edit("fractional alpha and selection", |doc, active| {
+            doc.layer_mut(active.unwrap()).unwrap().surface_mut().unwrap().write_region(photocraft_doc::Rect::new(2, 0, 3, 1), &[0.7, 0.2, 0.6, 0.7]);
+            doc.selection = Some(photocraft_raster::Surface::with_default(photocraft_doc::PixelFormat::GRAY8, &[coverage]));
+            Ok(())
+        })
+        .unwrap();
+        let before = s.active().unwrap().doc.clone();
+        let original = raw(&s);
+        s.execute("image.adjustments.replaceColor", json!({"labMinimum":[0,-128,-128],"labMaximum":[100,127,127],"lightness":100})).unwrap();
+        let after = raw(&s);
+        assert_ne!(&after[8..11], &original[8..11]);
+        for (after, before) in after.chunks_exact(4).zip(original.chunks_exact(4)) {
+            assert_eq!(after[3].to_bits(), before[3].to_bits(), "coverage {coverage}");
+        }
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
 /// A zero shift must not alter native ink values through an unnecessary RGB separation.
 #[test]
 fn an_unchanged_lab_tone_shift_preserves_native_cmyk_samples() {

From 409ba5829de889d5ce22b8e91cb3a230fdf53a22 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sun, 1 Nov 2026 17:37:14 -0800
Subject: [PATCH 037/109] Actions: Check Spelling records and saves as the
 spellCheck event

Recording Check Spelling now adds one edit.checkSpelling step,
{"allLayers"} with Check All Layers as the dialog has it on Done, with
the step's dialog on. The dialog's corrections, dictionary edits and
lookups, and the canvas spelling suggestions, are not recorded.

Load Actions maps the spellCheck event (null = the spellCheck property
of all text layers, Usng = checkAll) to that step, keeping its dialog
flag, and Save Actions writes the same descriptor back. Any other form
of the event stays a kept Photoshop step.

Played with its dialog on, the step opens Check Spelling with Check All
Layers as recorded, and Done continues the action. With its dialog off,
or headless, it checks and changes nothing.
---
 crates/engine/src/cmd/actions_cmds.rs         | 16 +++-
 crates/engine/src/cmd/atn_cmds/events.rs      | 43 ++++++++++-
 crates/engine/src/cmd/atn_cmds/tests.rs       | 65 +++++++++++++++++
 .../src/cmd/layer_multi_cmds/selection.rs     |  6 +-
 crates/engine/src/cmd/type_spell_cmds.rs      | 73 +++++++++++++------
 crates/engine/src/jobs.rs                     |  1 +
 crates/ui-egui/src/panels/actions.rs          | 41 +++++++++--
 crates/ui-egui/src/panels/actions/tests.rs    | 36 +++++++++
 crates/ui-egui/src/panels/type_panels_ui.rs   | 43 ++++++++++-
 9 files changed, 282 insertions(+), 42 deletions(-)

diff --git a/crates/engine/src/cmd/actions_cmds.rs b/crates/engine/src/cmd/actions_cmds.rs
index ea68d86b50..d436b0e48c 100644
--- a/crates/engine/src/cmd/actions_cmds.rs
+++ b/crates/engine/src/cmd/actions_cmds.rs
@@ -390,10 +390,19 @@ fn record(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({"action": name, "index": idx}))
 }
 
+/// Whether a journal entry is recorded as an action step: a replayable command, except Check
+/// Spelling's corrections and lookups.
+fn recorded(id: &str, p: &Value) -> bool {
+    replayable(id) && (id != "edit.checkSpelling" || crate::type_spell_cmds::records(p))
+}
+
+/// Commands recorded with their step's dialog on: Check Spelling.
+const RECORDED_WITH_DIALOG: &[&str] = &["edit.checkSpelling"];
+
 /// Replayable journal entries not yet committed to this action while recording.
 pub fn pending_steps(s: &Session, action: usize) -> impl Iterator<Item = &(String, Value)> {
     let from = s.actions.recording.filter(|(_, i)| *i == action).map_or(s.journal.len(), |(from, _)| from);
-    s.journal.iter().skip(from).filter(|(id, _)| replayable(id))
+    s.journal.iter().skip(from).filter(|(id, p)| recorded(id, p))
 }
 
 pub(crate) fn flush_recording(s: &mut Session) -> Result<()> {
@@ -404,7 +413,10 @@ pub(crate) fn flush_recording(s: &mut Session) -> Result<()> {
     let steps: Vec<_> = pending_steps(s, idx).cloned().collect();
     s.actions.recording = Some((s.journal.len(), idx));
     if !steps.is_empty() {
-        s.actions.list[idx].steps.extend(steps);
+        let action = &mut s.actions.list[idx];
+        let first = action.steps.len();
+        action.dialogs.extend(steps.iter().enumerate().filter(|(_, (id, _))| RECORDED_WITH_DIALOG.contains(&id.as_str())).map(|(i, _)| first + i));
+        action.steps.extend(steps);
         s.actions.touch();
     }
     Ok(())
diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index e84e60b351..47c68a0a68 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -1,6 +1,6 @@
 const DIFFUSE_MODE: &[(&str, &str)] = &[("Nrml", "normal"), ("DrkO", "darkenOnly"), ("LghO", "lightenOnly"), ("Anst", "anisotropic")];
 use super::adjustments::{adjustment_by_class, adjustment_steps, levels_from, levels_to, shadows_highlights_from, shadows_highlights_to};
-use super::descriptors::{desc, get_bool, get_ref, jbool, layer_ref, layer_target, ref_class};
+use super::descriptors::{class, code, desc, get_bool, get_obj, get_ref, jbool, layer_ref, layer_target, ref_class, trimmed};
 use super::fields::{F, Kind, Mapped, fields_from, fields_to, none, step};
 use super::steps_doc::{
     align_from, align_to, canvas_size_from, canvas_size_to, close_from, close_to, conditional_from, conditional_to, convert_mode_from, convert_mode_to,
@@ -17,7 +17,7 @@ use super::steps_layer::{
 };
 use super::steps_make::{locking_from, locking_to, make_from, make_to, set_from, set_to};
 use super::tables::{NOISE, OFFSET_FILL, SMART_BLUR_MODE, SMART_BLUR_QUALITY, TRIM};
-use super::{AtnEvent, D, Descriptor, STOP_MESSAGE, Value, json};
+use super::{AtnEvent, D, Descriptor, Id, ReferenceItem, STOP_MESSAGE, Value, json};
 
 /// An event: code (empty when Photoshop only has a string name), string name, the panel
 /// label, the command ids it exports (the first is the one simple events import to), and the
@@ -175,6 +175,44 @@ fn clipping_to(_: &str, p: &Value) -> Option<Descriptor> {
     Some(desc("null").with("null", layer_ref(p)?))
 }
 
+/// Check Spelling's `null`: the `spellCheck` property of all text layers.
+fn spell_check_ref() -> D {
+    D::Reference(vec![
+        ReferenceItem::Property { class: class("Prpr"), key: Id::new("spellCheck") },
+        ReferenceItem::Enumerated { class: class("TxLr"), type_id: code("Ordn"), value: code("Al") },
+    ])
+}
+
+/// Edit › Check Spelling (`spellCheck`): `null` is [`spell_check_ref`] and `Usng` holds only
+/// `checkAll`. Any other form stays a kept Photoshop step.
+fn spell_check_from(d: &Descriptor) -> Mapped {
+    let same_ref = |r: &[ReferenceItem]| match r {
+        [ReferenceItem::Property { class: p, key }, ReferenceItem::Enumerated { class: t, type_id, value }] => {
+            trimmed(&p.class_id) == "Prpr" && key.is("spellCheck") && trimmed(&t.class_id) == "TxLr" && trimmed(type_id) == "Ordn" && trimmed(value) == "Al"
+        }
+        _ => false,
+    };
+    let keys: Vec<String> = d.items.iter().map(|(k, _)| trimmed(k)).collect();
+    let using = get_obj(d, "Usng").filter(|u| u.class_id.is("spellCheck") && u.items.len() == 1);
+    match (keys.as_slice(), get_ref(d, "null"), using.and_then(|u| get_bool(u, "checkAll"))) {
+        ([null, usng], Some(r), Some(all)) if null == "null" && usng == "Usng" && same_ref(r) => step("edit.checkSpelling", json!({"allLayers": all})),
+        _ => Mapped::Unsupported { harmless: false },
+    }
+}
+
+/// A Check Spelling step that holds nothing but `allLayers` (Check All Layers, on by default).
+fn spell_check_to(_: &str, p: &Value) -> Option<Descriptor> {
+    let params = p.as_object()?;
+    if params.keys().any(|k| k != "allLayers") {
+        return None;
+    }
+    let all = match params.get("allLayers") {
+        None => true,
+        Some(v) => v.as_bool()?,
+    };
+    Some(desc("null").with("null", spell_check_ref()).with("Usng", D::Descriptor(desc("spellCheck").with("checkAll", D::Boolean(all)))))
+}
+
 /// A clipping mask event: `clipping_from` / `clipping_to` with one command id.
 macro_rules! clipping_event {
     ($code:literal, $name:literal, $label:literal, $id:literal) => {
@@ -581,6 +619,7 @@ pub(super) const EVENTS: &[Event] = &[
     },
     Event { code: "Rset", name: "reset", label: "Reset", ids: &["tools.defaultColors"], from: reset_from, to: reset_to },
     ev!("Exch", "exchange", "Exchange", "tools.swapColors", &[]),
+    Event { code: "", name: "spellCheck", label: "Check Spelling", ids: &["edit.checkSpelling"], from: spell_check_from, to: spell_check_to },
     Event {
         code: "",
         name: "assignProfile",
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 5de5928052..24f09e2e5b 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -597,6 +597,8 @@ fn every_mapped_command_exports_and_imports_back() {
         ("edit.pasteSpecial.pasteInPlace", json!({})),
         ("edit.paste", json!({})),
         ("edit.purge.histories", json!({})),
+        ("edit.checkSpelling", json!({"allLayers": true})),
+        ("edit.checkSpelling", json!({"allLayers": false})),
         ("tools.defaultColors", json!({})),
         ("edit.convertToProfile", json!({"profile": "display-p3", "intent": "perceptual", "bpc": false})),
         ("edit.assignProfile", json!({"profile": "srgb"})),
@@ -3805,3 +3807,66 @@ fn load_rejects_bad_encodings() {
     }
     assert!(s.actions.list.is_empty(), "nothing is loaded when the encoding is bad");
 }
+
+/// Edit › Check Spelling in its recorded form: `spellCheck`, `null` = the `spellCheck` property of
+/// all text layers, `Usng` = `checkAll`, with the step's dialog on.
+fn spell_check(all: bool) -> Descriptor {
+    desc("null")
+        .with(
+            "null",
+            D::Reference(vec![
+                ReferenceItem::Property { class: class("Prpr"), key: Id::new("spellCheck") },
+                ReferenceItem::Enumerated { class: class("TxLr"), type_id: code("Ordn"), value: code("Al") },
+            ]),
+        )
+        .with("Usng", D::Descriptor(desc("spellCheck").with("checkAll", D::Boolean(all))))
+}
+
+#[test]
+fn check_spelling_loads_and_saves_as_the_spell_check_event() {
+    for all in [true, false] {
+        let mut step = item("spellCheck", "Check Spelling", Some(spell_check(all)));
+        step.with_dialog = true;
+        let file = AtnFile {
+            name: UnicodeString::new_nul("S"),
+            actions: vec![AtnAction { name: UnicodeString::new_nul("A"), items: vec![step], ..Default::default() }],
+            ..Default::default()
+        };
+        let imported = import(&atn::write(&file).unwrap()).unwrap();
+        assert!(imported.unsupported.is_empty(), "{:?}", imported.unsupported);
+        let action = &imported.actions[0];
+        assert_eq!(action.steps, [("edit.checkSpelling".to_string(), json!({"allLayers": all}))]);
+        assert_eq!(action.dialogs.iter().copied().collect::<Vec<_>>(), [0]);
+        let (bytes, skipped) = export("S", &[action], &[], false).unwrap();
+        assert!(skipped.is_empty());
+        let saved = atn::parse(&bytes).unwrap();
+        let saved = &saved.actions[0].items[0];
+        assert_eq!(saved.event.id(), "spellCheck");
+        assert!(saved.with_dialog);
+        assert_eq!(saved.descriptor.as_ref().unwrap().to_bytes(), spell_check(all).to_bytes(), "checkAll {all}");
+    }
+}
+
+#[test]
+fn other_check_spelling_forms_stay_kept_steps_and_corrections_are_not_saved() {
+    let event = event_for(&AtnEvent::name("spellCheck")).unwrap();
+    let mut extra = spell_check(true);
+    extra.items.push((Id::new("Fwd "), D::Boolean(true)));
+    let mut other_target = spell_check(true);
+    other_target.items[0].1 = D::Reference(vec![ReferenceItem::Property { class: class("Prpr"), key: Id::new("spellCheck") }]);
+    let mut other_class = spell_check(true);
+    other_class.items[1].1 = D::Descriptor(desc("findReplace").with("checkAll", D::Boolean(true)));
+    let mut more_using = spell_check(true);
+    more_using.items[1].1 = D::Descriptor(desc("spellCheck").with("checkAll", D::Boolean(true)).with("Fwd ", D::Boolean(true)));
+    for d in [extra, other_target, other_class, more_using, desc("null")] {
+        assert!(matches!((event.from)(&d), Mapped::Unsupported { harmless: false }), "{d:?}");
+    }
+    for params in [
+        json!({"action": "change", "start": 0, "end": 3, "replace": "The"}),
+        json!({"action": "changeAll", "word": "teh", "replace": "the"}),
+        json!({"allLayers": true, "layer": "Title"}),
+        json!({"allLayers": "yes"}),
+    ] {
+        assert!(export_item("edit.checkSpelling", &params, "S").is_none(), "{params}");
+    }
+}
diff --git a/crates/engine/src/cmd/layer_multi_cmds/selection.rs b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
index 8efcbe3783..a0b5f76a77 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/selection.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
@@ -131,8 +131,7 @@ pub(super) fn same_named_targets(doc: &photocraft_doc::Document, name: &str, mov
 /// For `layer.select`, captures the layer by name. For other commands, if a numeric `layer`
 /// parameter references the document's sole selected layer, normalises it to the target form
 /// (omitting `layer`) so that the recorded step applies to whatever layer is targeted when
-/// replayed or exported to `.atn` (#7248). When it drops `layer` from an `edit.checkSpelling` step,
-/// it also records `"allLayers": false`.
+/// replayed or exported to `.atn` (#7248).
 pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Option<&[LayerId]>) -> Value {
     if id == "layer.select" {
         return recorded_selection(s, p);
@@ -157,9 +156,6 @@ pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Optio
         let mut p = p;
         if let Some(fields) = p.as_object_mut() {
             fields.remove("layer");
-            if id == "edit.checkSpelling" {
-                fields.insert("allLayers".into(), json!(false));
-            }
         }
         return p;
     }
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index 6ae2182e47..de067832ca 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -4,7 +4,8 @@
 //! (`photocraft_text::spell`, SCOWL size 50) plus the user dictionary in the preferences
 //! (`userDictionary`). Headless, it lists misspellings with suggestions and changes, changes all,
 //! or adds words to the dictionary; the UI's dialog drives the same actions. Offsets are
-//! character indices.
+//! character indices. An action records Check Spelling as one `{"allLayers"}` step with its
+//! dialog on, and records none of the corrections.
 //!
 //! `type.insertText` inserts a string (a glyph) into a type layer at a character position or
 //! over a range.
@@ -203,6 +204,18 @@ fn remove_word(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({ "removed": removed, "userDictionary": s.prefs().user_dictionary }))
 }
 
+/// Whether an action records this call: only Check Spelling itself (no `action`), which the
+/// dialog runs when it closes. Its corrections, dictionary edits and lookups are not recorded.
+pub(crate) fn records(p: &Value) -> bool {
+    p.get("action").is_none()
+}
+
+/// The step a recorded Check Spelling becomes: `{"allLayers"}`, `false` when it checked one layer.
+pub(crate) fn recorded_step(p: &Value) -> Value {
+    let one_layer = p.get("allLayers").and_then(Value::as_bool) == Some(false) || p.get("layer").is_some();
+    json!({ "allLayers": !one_layer })
+}
+
 fn check_spelling(s: &mut Session, p: &Value) -> Result<Value> {
     match p.get("action").and_then(Value::as_str).unwrap_or("list") {
         "list" | "check" => list(s, p),
@@ -270,7 +283,7 @@ pub fn specs() -> Vec<CommandSpec> {
             label: "Check Spelling…",
             menu: &["Edit"],
             shortcut: None,
-            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer"? (default: the active layer),"start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"}"#,
+            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer"? (default: the active layer),"start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"} (an action records only a call without "action", as {"allLayers"} with its dialog on)"#,
             enabled: has_type,
             journal: true,
             run: check_spelling,
@@ -378,36 +391,48 @@ mod tests {
     }
 
     #[test]
-    fn recorded_change_on_the_selected_layer_plays_on_another_document() {
-        let (mut s, id) = session("Teh end");
+    fn recording_keeps_check_spelling_with_its_dialog_and_not_its_corrections() {
+        let (mut s, id) = session("Teh brwon end");
         s.execute("actions.record", json!({"name": "Spell"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "list", "allLayers": true})).unwrap();
         s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "changeAll", "word": "brwon", "replace": "brown"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "suggest", "word": "recieve"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "addToDictionary", "word": "Photocraft"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "removeFromDictionary", "word": "Photocraft"})).unwrap();
+        // The dialog closing.
+        s.execute("edit.checkSpelling", json!({"allLayers": true, "suggestions": 8})).unwrap();
         s.execute("actions.stop", json!({})).unwrap();
-        assert_eq!(text_of(&s, id), "The end");
-        // The recorded step names no layer, so it acts on the layer targeted when it plays.
-        assert!(s.actions.list[0].steps[0].1.get("layer").is_none(), "{:?}", s.actions.list[0].steps);
-        s.execute("file.new", json!({"width": 300, "height": 100, "background": "white"})).unwrap();
-        let other = s.execute("type.create", json!({"x": 10, "y": 50, "text": "Teh end", "size": 12})).unwrap()["layer"].as_u64().unwrap();
-        let r = s.execute("actions.play", json!({"action": "Spell"})).unwrap();
-        assert!(r.get("failed").is_none(), "{r}");
-        assert_eq!(r["ran"], 1);
-        assert_eq!(text_of(&s, other), "The end");
+        assert_eq!(text_of(&s, id), "The brown end");
+        let action = &s.actions.list[0];
+        assert_eq!(action.steps, vec![("edit.checkSpelling".to_string(), json!({"allLayers": true}))]);
+        assert_eq!(action.dialogs.iter().copied().collect::<Vec<_>>(), [0]);
     }
 
     #[test]
-    fn recorded_change_all_on_the_selected_layer_plays_on_that_layer_only() {
-        let (mut s, a) = session("teh one");
-        let b = s.execute("type.create", json!({"x": 10, "y": 90, "text": "teh two", "size": 12})).unwrap()["layer"].as_u64().unwrap();
-        s.execute("layer.select", json!({"layer": a})).unwrap();
-        s.execute("actions.record", json!({"name": "All"})).unwrap();
-        s.execute("edit.checkSpelling", json!({"action": "changeAll", "layer": a, "word": "teh", "replace": "the"})).unwrap();
+    fn recorded_check_of_one_layer_records_all_layers_off() {
+        let (mut s, id) = session("Teh end");
+        s.execute("actions.record", json!({"name": "One"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"allLayers": false})).unwrap();
+        s.execute("edit.checkSpelling", json!({"layer": id})).unwrap();
         s.execute("actions.stop", json!({})).unwrap();
-        assert_eq!((text_of(&s, a).as_str(), text_of(&s, b).as_str()), ("the one", "teh two"));
-        s.execute("edit.undo", json!({})).unwrap();
-        s.execute("layer.select", json!({"layer": a})).unwrap();
-        let r = s.execute("actions.play", json!({"action": "All"})).unwrap();
+        let steps: Vec<&Value> = s.actions.list[0].steps.iter().map(|(_, p)| p).collect();
+        assert_eq!(steps, [&json!({"allLayers": false}), &json!({"allLayers": false})]);
+        assert_eq!(s.actions.list[0].dialogs.len(), 2);
+    }
+
+    #[test]
+    fn played_check_spelling_without_its_dialog_changes_nothing() {
+        let (mut s, id) = session("Teh end");
+        s.execute("actions.record", json!({"name": "Spell"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"allLayers": true})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        let history = s.active().unwrap().history.past_len();
+        let r = s.execute("actions.play", json!({"action": "Spell"})).unwrap();
         assert!(r.get("failed").is_none(), "{r}");
-        assert_eq!((text_of(&s, a).as_str(), text_of(&s, b).as_str()), ("the one", "teh two"));
+        assert_eq!(r["ran"], 1);
+        assert_eq!(text_of(&s, id), "Teh end");
+        assert_eq!(s.active().unwrap().history.past_len(), history);
     }
 
     #[test]
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index ac9e38a723..9f237605ef 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -964,6 +964,7 @@ impl Session {
                 _ if self.actions.recording.is_none() => params,
                 "layer.duplicate" => crate::artboard_cmds::recorded_duplicate(self, crate::layer_multi_cmds::recorded_step(self, id, params, pre_selected)),
                 "layerComp.apply" => crate::comps_cmds::recorded_apply(self, params),
+                "edit.checkSpelling" if crate::type_spell_cmds::records(&params) => crate::type_spell_cmds::recorded_step(&params),
                 _ => crate::layer_multi_cmds::recorded_step(self, id, params, pre_selected),
             };
             let params = crate::actions_cmds::recorded_params(self, id, params);
diff --git a/crates/ui-egui/src/panels/actions.rs b/crates/ui-egui/src/panels/actions.rs
index 88034ab2c8..96a806975c 100644
--- a/crates/ui-egui/src/panels/actions.rs
+++ b/crates/ui-egui/src/panels/actions.rs
@@ -109,7 +109,7 @@ fn play_targets(app: &mut PhotocraftApp, targets: &[usize], before: u64) -> Resu
         let mut v = app.run("actions.play", json!({"action": i}))?;
         ran = ran.saturating_add(v.get("ran").and_then(Value::as_u64).unwrap_or(0));
         let failed = v.get("failed").is_some_and(Value::is_object);
-        let paused = v.get("paused").filter(|p| p.is_object()).and_then(|p| p.get("dialog")).and_then(Value::as_u64);
+        let paused = v.get("paused").filter(|p| p.is_object()).and_then(waiting_dialog).cloned();
         if let Some(o) = v.as_object_mut() {
             o.insert("ran".into(), json!(ran));
         }
@@ -119,7 +119,7 @@ fn play_targets(app: &mut PhotocraftApp, targets: &[usize], before: u64) -> Resu
             // (`actions.move`), and one deleted and made again under its name isn't the same action.
             let list = &app.session.actions.list;
             let rest: Vec<Action> = targets.get(n + 1..).unwrap_or_default().iter().filter_map(|i| list.get(*i).cloned()).collect();
-            let token = app.ui.dialog_mut(dialog).and_then(|d| d.fields.get(RESUME)).and_then(Value::as_u64);
+            let token = paused_token(app, &dialog);
             if let Some(entry) = token.and_then(|t| app.paused_playbacks.paused.get_mut(&t))
                 && name.as_ref() == Some(&entry.action)
             {
@@ -135,6 +135,19 @@ fn play_targets(app: &mut PhotocraftApp, targets: &[usize], before: u64) -> Resu
     Ok(last)
 }
 
+/// The dialog a paused playback waits at: a step dialog by id, or Check Spelling.
+fn waiting_dialog(paused: &Value) -> Option<&Value> {
+    paused.get("dialog").filter(|d| d.is_u64() || d.as_str() == Some(crate::type_panels_ui::SPELLING))
+}
+
+/// The token of the paused playback waiting at `dialog` (see [`waiting_dialog`]).
+fn paused_token(app: &mut PhotocraftApp, dialog: &Value) -> Option<u64> {
+    match dialog.as_u64() {
+        Some(id) => app.ui.dialog_mut(id).and_then(|d| d.fields.get(RESUME)).and_then(Value::as_u64),
+        None => app.ui.type_panels.spell.as_ref().and_then(|d| d.resume),
+    }
+}
+
 /// Index of the playback target. Photoshop's Play button uses the first action when
 /// the panel has actions but none of its rows is selected.
 fn playback_selection(app: &PhotocraftApp) -> Option<usize> {
@@ -239,6 +252,19 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
             paused = Some(json!({"step": i, "id": id, "dialog": dialog}));
             break;
         }
+        // Check Spelling's dialog opens with Check All Layers as recorded; Done continues the action.
+        if action.dialogs.contains(&i) && !app.automation_input && id == "edit.checkSpelling" {
+            if let Err(error) = crate::type_panels_ui::open_spelling(app, p.get("allLayers").and_then(Value::as_bool).unwrap_or(true)) {
+                failed = Some(json!({"step": i, "id": id, "error": error}));
+                break;
+            }
+            let token = app.paused_playbacks.pause(action.name.clone(), i + 1, app.session.authorize);
+            if let Some(d) = app.ui.type_panels.spell.as_mut() {
+                d.resume = Some(token);
+            }
+            paused = Some(json!({"step": i, "id": id, "dialog": crate::type_panels_ui::SPELLING}));
+            break;
+        }
         let target = app.session.active().map(|d| d.doc.id);
         let result = if id == "actions.play" {
             play(app, p)
@@ -277,10 +303,11 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
         }
     }
     actions_cmds::finish_playback(&mut app.session, None, &action, from);
-    match paused.as_ref().and_then(|p| p.get("dialog")).and_then(Value::as_u64).and_then(|d| app.ui.dialog_mut(d)) {
+    match paused.as_ref().and_then(waiting_dialog).cloned() {
         // Paused for a dialog: the call goes on after it, so recording stays suspended.
-        Some(d) if failed.is_none() => {
-            let entry = d.fields.get(RESUME).and_then(Value::as_u64).and_then(|t| app.paused_playbacks.paused.get_mut(&t));
+        Some(dialog) if failed.is_none() => {
+            let token = paused_token(app, &dialog);
+            let entry = token.and_then(|t| app.paused_playbacks.paused.get_mut(&t));
             match (owner, entry) {
                 (Some(owner), Some(p)) => p.record = Some(owner),
                 // No continuation to carry the recording: the call ends here.
@@ -758,8 +785,8 @@ pub fn resume(app: &mut PhotocraftApp, fields: &serde_json::Map<String, Value>)
     // Paused again at a later dialog of the same action (not of one it calls, which resumes
     // alone): that dialog carries the rest of the set.
     if let Ok(v) = &played
-        && let Some(dialog) = v.get("paused").and_then(|p| p.get("dialog")).and_then(Value::as_u64)
-        && let Some(token) = app.ui.dialog_mut(dialog).and_then(|d| d.fields.get(RESUME)).and_then(Value::as_u64)
+        && let Some(dialog) = v.get("paused").and_then(waiting_dialog)
+        && let Some(token) = paused_token(app, dialog)
         && let Some(entry) = app.paused_playbacks.paused.get_mut(&token)
         && entry.action == paused.action
     {
diff --git a/crates/ui-egui/src/panels/actions/tests.rs b/crates/ui-egui/src/panels/actions/tests.rs
index 06a5cd5fb3..6049cdb5ad 100644
--- a/crates/ui-egui/src/panels/actions/tests.rs
+++ b/crates/ui-egui/src/panels/actions/tests.rs
@@ -1377,6 +1377,42 @@ fn dialog_worker_failure_stops_action_before_following_steps() {
     }
 }
 
+#[test]
+fn a_check_spelling_step_with_its_dialog_opens_it_and_done_continues() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let mut a = Action::new("Spell", vec![("edit.checkSpelling".into(), json!({"allLayers": false})), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!((v["ran"].as_u64(), v["paused"]["step"].as_u64()), (Some(0), Some(0)), "{v}");
+    assert_eq!(v["paused"]["dialog"], crate::type_panels_ui::SPELLING);
+    let d = app.ui.type_panels.spell.clone().expect("Check Spelling is open");
+    assert!(!d.all_layers, "the dialog opens with Check All Layers as recorded");
+    assert_eq!(d.items.len(), 1);
+    assert!(!layer_names(&app).contains(&"after".to_string()), "nothing after the dialog ran yet");
+    crate::type_panels_ui::close_spelling(&mut app);
+    assert!(layer_names(&app).contains(&"after".to_string()), "Done played the rest");
+    assert!(app.ui.status.starts_with("Played"), "{}", app.ui.status);
+    // With its dialog off, the step checks without opening anything and changes nothing.
+    app.session.actions.list[0].dialogs.clear();
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["ran"], 2, "{v}");
+    assert!(app.ui.type_panels.spell.is_none());
+    let st = app.session.active().unwrap();
+    let texts: Vec<String> = st
+        .doc
+        .walk()
+        .into_iter()
+        .filter_map(|(_, _, l)| match &l.content {
+            photocraft_doc::LayerContent::Text(t) => Some(t.text.clone()),
+            _ => None,
+        })
+        .collect();
+    assert_eq!(texts, ["Teh cat"]);
+}
+
 #[test]
 fn a_dialog_toggled_step_pauses_playback_and_resumes_on_ok() {
     let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
diff --git a/crates/ui-egui/src/panels/type_panels_ui.rs b/crates/ui-egui/src/panels/type_panels_ui.rs
index d95c22addb..dbcb140788 100644
--- a/crates/ui-egui/src/panels/type_panels_ui.rs
+++ b/crates/ui-egui/src/panels/type_panels_ui.rs
@@ -48,8 +48,15 @@ pub struct SpellDialog {
     pub change_to: String,
     pub all_layers: bool,
     pub message: String,
+    /// The token of the action playback that opened the dialog at a Check Spelling step: Done
+    /// continues it ([`crate::actions::resume`]).
+    #[serde(skip)]
+    pub resume: Option<u64>,
 }
 
+/// The `dialog` that Check Spelling's results and a playback paused at its step name.
+pub const SPELLING: &str = "checkSpelling";
+
 const IDS: [&str; 6] = [
     "type.panels.characterStyles",
     "window.panel.characterStyles",
@@ -772,7 +779,20 @@ pub fn open_spelling(app: &mut PhotocraftApp, all_layers: bool) -> Result<Value,
     app.ui.type_panels.spell = Some(SpellDialog { all_layers, ..Default::default() });
     refresh_spelling(app);
     let d = app.ui.type_panels.spell.as_ref().map(|d| d.items.clone()).unwrap_or_default();
-    Ok(json!({ "dialog": "checkSpelling", "misspellings": d }))
+    Ok(json!({ "dialog": SPELLING, "misspellings": d }))
+}
+
+/// Done: an action being recorded gets one Check Spelling step with Check All Layers as the dialog
+/// has it, and an action paused at a Check Spelling step continues.
+pub fn close_spelling(app: &mut PhotocraftApp) {
+    let Some(d) = app.ui.type_panels.spell.take() else { return };
+    if app.session.actions.recording.is_some() {
+        let _ = run(app, "edit.checkSpelling", json!({ "allLayers": d.all_layers }));
+    }
+    if let Some(token) = d.resume {
+        let fields = serde_json::Map::from_iter([(crate::actions::RESUME.to_string(), json!(token))]);
+        let _ = crate::actions::resume(app, &fields);
+    }
 }
 
 fn spelling_window(app: &mut PhotocraftApp, ctx: &egui::Context) {
@@ -875,7 +895,7 @@ fn spelling_window(app: &mut PhotocraftApp, ctx: &egui::Context) {
     let Some(a) = act else { return };
     let word = item.as_ref().and_then(|i| i["word"].as_str()).unwrap_or("").to_string();
     match a {
-        "done" => app.ui.type_panels.spell = None,
+        "done" => close_spelling(app),
         "relist" => {
             if let Some(s) = app.ui.type_panels.spell.as_mut() {
                 s.index = 0;
@@ -964,6 +984,25 @@ mod tests {
         assert!(menu(&mut app, "edit.checkSpelling", &json!({"action": "list"})).is_none());
     }
 
+    #[test]
+    fn recording_the_dialog_records_one_step_with_its_dialog_on() {
+        let mut app = app_with_text("Teh cat");
+        app.run("actions.record", json!({"name": "Spell"})).unwrap();
+        menu(&mut app, "edit.checkSpelling", &json!({})).unwrap().unwrap();
+        let item = app.ui.type_panels.spell.as_ref().unwrap().items[0].clone();
+        // Change, as the dialog's Change button runs it, then untick Check All Layers and press Done.
+        let change = json!({"action": "change", "layer": item["layer"], "start": item["start"], "end": item["end"], "word": "Teh", "replace": "The"});
+        run(&mut app, "edit.checkSpelling", change).unwrap();
+        refresh_spelling(&mut app);
+        app.ui.type_panels.spell.as_mut().unwrap().all_layers = false;
+        close_spelling(&mut app);
+        app.run("actions.stop", json!({})).unwrap();
+        assert!(app.ui.type_panels.spell.is_none());
+        let action = &app.session.actions.list[0];
+        assert_eq!(action.steps, vec![("edit.checkSpelling".to_string(), json!({"allLayers": false}))]);
+        assert_eq!(action.dialogs.iter().copied().collect::<Vec<_>>(), [0]);
+    }
+
     /// #5496: Check Spelling's close box is Done, as in Photoshop on Windows: the window closes
     /// and the text keeps what it had. None on macOS.
     #[test]

From 7b0d68c8e3cd00d99d3ff7dabcb8a2f8aeee7ff4 Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 17:42:52 -0800
Subject: [PATCH 038/109] Fix Artboard action round trips and singleton links

---
 crates/engine/src/cmd/artboard_cmds.rs        |  1 +
 .../engine/src/cmd/atn_cmds/steps_artboard.rs | 35 +++++++--
 crates/engine/src/cmd/atn_cmds/tests.rs       |  7 ++
 .../src/cmd/layer_multi_cmds/structure.rs     |  5 +-
 crates/engine/tests/it/atn_newer_events.rs    | 71 ++++++++++++++++++-
 docs/atn.md                                   |  3 +
 docs/file-format-parity.md                    |  4 +-
 7 files changed, 115 insertions(+), 11 deletions(-)

diff --git a/crates/engine/src/cmd/artboard_cmds.rs b/crates/engine/src/cmd/artboard_cmds.rs
index c3ba0dd2dd..bc4d9e8980 100644
--- a/crates/engine/src/cmd/artboard_cmds.rs
+++ b/crates/engine/src/cmd/artboard_cmds.rs
@@ -332,6 +332,7 @@ fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
         *active = Some(id);
         Ok(rect)
     })?;
+    crate::layer_multi_cmds::set_selection(s, vec![id], Some(id), Some(id))?;
     Ok(json!({"layer": id.0, "rect": [rect.x0, rect.y0, rect.width(), rect.height()]}))
 }
 
diff --git a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
index 43115b3b1c..b03adcffc2 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
@@ -20,8 +20,12 @@ fn settings_from(board: &Descriptor, preset_key: &str) -> Option<Value> {
     };
     let Some(D::List(guides)) = board.get("guideIDs") else { return None };
     let guides: Vec<i32> = guides.iter().map(|v| if let D::Integer(n) = v { Some(*n) } else { None }).collect::<Option<_>>()?;
-    let rgb: Vec<f64> = ["Rd  ", "Grn ", "Bl  "].iter().map(|key| get_num(color, key).map(|n| n / 255.0)).collect::<Option<_>>()?;
+    let recorded: Vec<f64> = ["Rd  ", "Grn ", "Bl  "].iter().map(|key| get_num(color, key)).collect::<Option<_>>()?;
+    let rgb: Vec<f64> = recorded.iter().map(|n| n / 255.0).collect();
     let mut p = json!({"background": background, "color": rgb, "guideIDs": guides});
+    if recorded.iter().zip(&rgb).any(|(recorded, native)| *recorded != native * 255.0) {
+        p["recordedColor"] = json!(recorded);
+    }
     p[preset_key] = preset.into();
     if board.get("artboardBackgroundType").is_none() {
         p["backgroundTypeOmitted"] = true.into();
@@ -48,7 +52,17 @@ fn settings_to(p: &Value, preset_key: &str) -> Option<Descriptor> {
     if !rgb.iter().all(|n| n.is_finite() && (0.0..=1.0).contains(n)) {
         return None;
     }
-    let color = ["Rd  ", "Grn ", "Bl  "].into_iter().zip(rgb).fold(desc("RGBC"), |d, (key, n)| d.with(key, D::Double(n * 255.0)));
+    let recorded = match p.get("recordedColor") {
+        None => rgb.iter().map(|n| n * 255.0).collect(),
+        Some(value) => {
+            let values = value.as_array()?.iter().map(Value::as_f64).collect::<Option<Vec<_>>>()?;
+            if values.len() != 3 || values.iter().zip(&rgb).any(|(wire, native)| !(0.0..=255.0).contains(wire) || wire / 255.0 != *native) {
+                return None;
+            }
+            values
+        }
+    };
+    let color = ["Rd  ", "Grn ", "Bl  "].into_iter().zip(recorded).fold(desc("RGBC"), |d, (key, n)| d.with(key, D::Double(n)));
     let board = desc("artboard").with("guideIDs", D::List(guides)).with("artboardPresetName", text(preset)).with("Clr ", D::Descriptor(color));
     match p.get("backgroundTypeOmitted") {
         None => Some(board.with("artboardBackgroundType", D::Integer(background))),
@@ -72,17 +86,25 @@ pub(super) fn artboard_from(d: &Descriptor) -> Mapped {
     if artboard_to(FROM_GROUP, &p).is_some_and(|expected| expected.items == d.items) { step(FROM_GROUP, p) } else { unsupported }
 }
 
-/// Save complete recorded conversion settings; unknown native options must not disappear.
+/// Fill behavior-neutral metadata for native settings; unknown options must not disappear.
 pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
     let fields = p.as_object()?;
     let d = desc("null").with("null", target_ref("Lyr "));
     if fields.is_empty() {
         return Some(d);
     }
-    if fields.keys().any(|k| !["background", "color", "preset", "guideIDs", "changeBackground", "backgroundTypeOmitted"].contains(&k.as_str())) {
+    if fields.keys().any(|k| !["background", "color", "recordedColor", "preset", "guideIDs", "changeBackground", "backgroundTypeOmitted"].contains(&k.as_str()))
+    {
         return None;
     }
-    let d = d.with("artboard", D::Descriptor(settings_to(p, "preset")?));
+    let mut settings = p.clone();
+    let fields = settings.as_object_mut()?;
+    let background = if fields.contains_key("color") { "custom" } else { "white" };
+    // Native custom-without-color means white. Other types ignore this last-used color.
+    for (key, value) in [("background", json!(background)), ("color", json!([1.0, 1.0, 1.0])), ("preset", json!("")), ("guideIDs", json!([]))] {
+        fields.entry(key).or_insert(value);
+    }
+    let d = d.with("artboard", D::Descriptor(settings_to(&settings, "preset")?));
     match p.get("changeBackground") {
         None => Some(d),
         // Older native action files used true for the recorded integer 1.
@@ -108,7 +130,8 @@ pub(super) fn artboard_edit_from(d: &Descriptor) -> Mapped {
 pub(super) fn artboard_edit_to(_: &str, p: &Value) -> Option<Descriptor> {
     let fields = p.as_object()?;
     if fields.keys().any(|k| {
-        !["background", "color", "recordedPreset", "guideIDs", "recordedRect", "changeSizes", "changeBackground", "backgroundTypeOmitted"].contains(&k.as_str())
+        !["background", "color", "recordedColor", "recordedPreset", "guideIDs", "recordedRect", "changeSizes", "changeBackground", "backgroundTypeOmitted"]
+            .contains(&k.as_str())
     }) || p.get("changeSizes")?.as_i64()? != 8
         || p.get("changeBackground")?.as_i64()? != 1
     {
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 598f1c2d24..19e269a14c 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -737,6 +737,13 @@ fn every_mapped_command_exports_and_imports_back() {
             Mapped::Unsupported { .. } => panic!("{id} does not import back"),
         }
     }
+    // Partial native backgrounds need no recorded preset, guide IDs or last-used color.
+    for background in ["white", "black", "transparent", "custom"] {
+        let item = export_item("layer.new.artboardFromGroup", &json!({"background":background}), "S").unwrap();
+        let Mapped::Steps(steps) = (event_for(&item.event).unwrap().from)(item.descriptor.as_ref().unwrap()) else { panic!("Artboard did not import") };
+        assert_eq!(steps, [("layer.new.artboardFromGroup".into(), json!({"background":background,"color":[1.0,1.0,1.0],"preset":"","guideIDs":[]}))]);
+        assert_eq!(export_item(&steps[0].0, &steps[0].1, "S").unwrap().descriptor, item.descriptor);
+    }
     // Every command the table claims to export has a case above.
     let covered: std::collections::BTreeSet<&str> = cases.iter().map(|(id, _)| *id).collect();
     let mut missing: Vec<&str> = EVENTS.iter().flat_map(|e| e.ids.iter().copied()).filter(|id| !covered.contains(id)).collect();
diff --git a/crates/engine/src/cmd/layer_multi_cmds/structure.rs b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
index f5d4b2325f..228372e293 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/structure.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/structure.rs
@@ -17,13 +17,14 @@ pub(super) fn link_layers(s: &mut Session, p: &Value) -> Result<Value> {
     let same_group = first.is_some() && groups.iter().all(|group| *group == first);
     // A recorded Link/Unlink is an operation, not the UI's state-dependent toggle.
     // An explicit repeat must neither allocate a group nor add an undo entry.
-    if requested == Some(true) && same_group || requested == Some(false) && groups.iter().all(Option::is_none) {
+    let linked_group = same_group && doc.walk().iter().filter(|(_, _, layer)| layer.link_group == first).take(2).count() == 2;
+    if requested == Some(true) && linked_group || requested == Some(false) && groups.iter().all(Option::is_none) {
         return Ok(json!({"linked": requested == Some(true)}));
     }
     let label = if requested == Some(false) { "Unlink Layers" } else { "Link Layers" };
     let linked = s.edit(label, |doc, _| {
         // Already one link group (or a single linked layer): unlink, like Photoshop's toggle.
-        let unlink = requested.map_or(same_group, |linked| !linked);
+        let unlink = requested.map_or(same_group, |linked| !linked) || sel.len() < 2;
         // A loaded file can store any id up to u64::MAX, so the new id must not be a bare
         // max + 1 (#961). Unlinking needs no new id at all.
         let next = if unlink { None } else { Some(doc.unused_link_group().ok_or_else(|| bad("layer.linkLayers", "no free link group id is left"))?) };
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 816935cce8..55f6149f55 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -130,6 +130,26 @@ fn unlink_cleans_singletons_preserves_other_groups_and_undoes() {
     assert!(!one.is_enabled("layer.linkLayers"), "the UI toggle still requires two unlinked layers");
 }
 
+/// Explicit Link cleans an orphan without touching a real group's unselected member.
+#[test]
+fn explicit_link_cleans_a_singleton_but_preserves_a_linked_pair() {
+    for initial in [vec![Some(77)], vec![Some(77), None], vec![Some(77), Some(77)]] {
+        let mut s = fixture(&initial, &[0]);
+        let before = s.active().unwrap().doc.clone();
+        let history = s.active().unwrap().history.past_len();
+        let linked = initial == [Some(77), Some(77)];
+        assert_eq!(s.execute("layer.linkLayers", json!({"linked": true})).unwrap()["linked"], linked);
+        if linked {
+            assert_eq!(s.active().unwrap().doc, before);
+            assert_eq!(s.active().unwrap().history.past_len(), history);
+        } else {
+            assert!(groups(&s).iter().all(Option::is_none));
+            assert!(s.undo());
+            assert_eq!(s.active().unwrap().doc, before);
+        }
+    }
+}
+
 #[test]
 fn invalid_link_state_fails_without_editing() {
     let mut s = fixture(&[None, None], &[0, 1]);
@@ -511,6 +531,55 @@ fn artboard_target_only_form_keeps_existing_native_group_behavior() {
     assert_eq!(s.active().unwrap().doc, before);
 }
 
+/// A conversion selects its result, so a following Delete cannot remove another selected layer.
+#[test]
+fn artboard_from_group_replaces_the_previous_layer_selection() {
+    let mut s = artboard_fixture();
+    let group = s.active().unwrap().active_layer.unwrap();
+    let doc = Arc::make_mut(&mut s.active_mut().unwrap().doc);
+    let other = Layer::raster("Other", doc.pixel_format());
+    let id = other.id;
+    doc.layers.push(other);
+    s.restore_layer_selection(Some(group), &[id, group], Some(id)).unwrap();
+    load(&mut s, &file("artboardFromLayerGroupEvent", Descriptor::new("null").with("null", target())));
+    play(&mut s);
+    assert_eq!(s.active().unwrap().selected_layers(), vec![group]);
+    s.execute("layer.delete", json!({})).unwrap();
+    assert!(s.active().unwrap().doc.layer(id).is_some());
+    assert!(s.active().unwrap().doc.layer(group).is_none());
+}
+
+/// Preserve fractional wire values exactly while playback uses normalized native RGB.
+#[test]
+fn artboard_fractional_colors_survive_import_save_and_playback() {
+    let rgb = [7.97, 31.88, 127.6];
+    for event in ["artboardFromLayerGroupEvent", "editArtboardEvent"] {
+        let mut s = artboard_fixture();
+        let mut d = if event == "editArtboardEvent" {
+            s.execute("layer.new.artboardFromGroup", json!({})).unwrap();
+            artboard_edit_descriptor(4, 8)
+        } else {
+            artboard_descriptor(4, vec![], D::Integer(1))
+        };
+        let D::Descriptor(board) = &mut d.items.iter_mut().find(|(key, _)| key.is("artboard")).unwrap().1 else { unreachable!() };
+        board.items.iter_mut().find(|(key, _)| key.is("Clr ")).unwrap().1 =
+            D::Descriptor(["Rd  ", "Grn ", "Bl  "].into_iter().zip(rgb).fold(Descriptor::new("RGBC"), |color, (key, n)| color.with(key, D::Double(n))));
+        assert_eq!(load(&mut s, &file(event, d.clone()))["unsupported"], json!([]));
+        assert_eq!(saved_item(&mut s).descriptor, Some(d));
+        let (id, mut changed) = s.actions.list[0].steps[0].clone();
+        changed["color"][0] = 0.5.into();
+        assert!(atn_cmds::export("Links", &[&Action::new("Changed", vec![(id, changed)])], &[], false).is_err());
+        let before = s.active().unwrap().doc.clone();
+        play(&mut s);
+        let pixel = photocraft_compose::render(&s.active().unwrap().doc, photocraft_doc::Rect::new(3, 3, 4, 4)).px[0];
+        for (actual, expected) in pixel.into_iter().zip(rgb.map(|n| n as f32 / 255.0)) {
+            assert!((actual - expected).abs() < 0.005, "{event}: {pixel:?}");
+        }
+        assert!(s.undo());
+        assert_eq!(s.active().unwrap().doc, before);
+    }
+}
+
 /// Unproved settings remain byte-preserving kept steps and cannot partially edit the document.
 #[test]
 fn artboard_unmeasured_types_and_extra_settings_stay_whole() {
@@ -532,7 +601,7 @@ fn artboard_unmeasured_types_and_extra_settings_stay_whole() {
         assert_eq!(s.active().unwrap().doc, before);
         assert_eq!(s.active().unwrap().history.past_len(), history);
     }
-    for p in [json!({"layer":1}), json!({"preset":"iPhone 14"}), json!({"guideIDs":[]}), json!({"changeBackground":false})] {
+    for p in [json!({"layer":1}), json!({"preset":7}), json!({"guideIDs":[7.5]}), json!({"changeBackground":false})] {
         let action = Action::new("A", vec![("layer.new.artboardFromGroup".into(), p)]);
         assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
     }
diff --git a/docs/atn.md b/docs/atn.md
index 00e2852689..9d12d25bd2 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -440,6 +440,9 @@ commands record).
   makes a white artboard (type 1, `Clr ` 255/255/255), and the step's result then has no `changeBackground` key.
   `artboardBackgroundType` absent with `changeBackground` 1 gives type 1 (white).
 - The artboard takes the group's bounds; `Clr ` is stored on the artboard as given even when the type is 1..3.
+- PhotoCraft preserves fractional recorded RGB values exactly. Native actions with partial settings export an empty preset and guide list when absent.
+  An absent native color exports as white: it matches the native custom-color fallback and is visually ignored for white, black and transparent backgrounds.
+  This is canonical export metadata, not a claim about the reference application's remembered color. Imported steps retain their recorded color instead.
 
 ## Measured through dialogs and recordings
 
diff --git a/docs/file-format-parity.md b/docs/file-format-parity.md
index 51e931496a..f31262f535 100644
--- a/docs/file-format-parity.md
+++ b/docs/file-format-parity.md
@@ -148,8 +148,8 @@ Embedded SVG and PDF-compatible AI/PDF/EPS payloads can use an explicit VectorCr
 
 | Date | Change | Summary |
 |---|---|---|
-| 2026-11-01 | minor | `.atn`: 22 newer measured forms mapped, including explicit Link/Unlink, Smart Object file operations, Make Type to Shape, radius-only Shape Blur and the Crop Photos parent; 138 supported event names. Artboard from Group and generated Crop helper steps remain kept. |
-| 2026-11-01 | minor | `.atn`: event reference [atn.md](atn.md): the 117 supported events, and measured keys, defaults, ranges and enum values for 101 events not mapped yet |
+| 2026-11-01 | minor | `.atn`: 23 newer measured forms mapped, including explicit Link/Unlink, Smart Object file operations, Make Type to Shape, radius-only Shape Blur, Artboard from Group and the Crop Photos parent; 139 supported event names. Artboard forms with unmeasured settings and generated Crop helper steps remain kept. |
+| 2026-11-01 | minor | `.atn`: event reference [atn.md](atn.md): the 139 supported events, and measured keys, defaults, ranges and enum values for 101 events not mapped yet |
 | 2026-10-26 | minor | Embedded AI/PDF/EPS save-back retains native format and a separate source-bound display preview; original sources remain undoable. Native Adobe interoperability and standalone EPS/DCS remain unverified; no corpus floor or percentage changed. |
 | 2026-10-22 | minor | Embedded PSD vectors gain explicit bounded SVG editor/save-back; standalone EPS/DCS and native-format fidelity remain open. |
 | 2026-10-22 | minor | TIFF: flat pages up to 300,000 px a side open (was 2^30 px, about 32,768²): `codecs::TiffBands` decodes a group of rows at a time into the layer's tiles. The 117,504 × 22,464 px banner from #8456 opens in 3.3 s at 11.45 GB peak for a 10.56 GB layer; 30,000² 6.8 s / 6.43 GB → 1.1 s / 3.86 GB; 36 MP 220 → 52 ms. Layered TIFFs still decode whole (#8169) |

From 2ed2b32a84e74507a1e7685fb18332558b1f0f6f Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Sun, 1 Nov 2026 18:13:34 -0800
Subject: [PATCH 039/109] Actions: Check Spelling opened again keeps the
 waiting action's continuation

Opening Edit > Check Spelling again while an action waits at a Check
Spelling step keeps that action's continuation, so Done still plays
its remaining steps. A second playback that reaches a Check Spelling
step with its dialog on while the dialog is held for another action
fails at that step instead of taking the dialog over.
---
 crates/ui-egui/src/panels/actions.rs        |  5 ++++
 crates/ui-egui/src/panels/actions/tests.rs  | 26 +++++++++++++++++++++
 crates/ui-egui/src/panels/type_panels_ui.rs |  6 +++--
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/crates/ui-egui/src/panels/actions.rs b/crates/ui-egui/src/panels/actions.rs
index 96a806975c..6f7a435c19 100644
--- a/crates/ui-egui/src/panels/actions.rs
+++ b/crates/ui-egui/src/panels/actions.rs
@@ -253,7 +253,12 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
             break;
         }
         // Check Spelling's dialog opens with Check All Layers as recorded; Done continues the action.
+        // While another action waits at the open dialog, this step fails and the waiting one keeps it.
         if action.dialogs.contains(&i) && !app.automation_input && id == "edit.checkSpelling" {
+            if app.ui.type_panels.spell.as_ref().is_some_and(|d| d.resume.is_some()) {
+                failed = Some(json!({"step": i, "id": id, "error": "Check Spelling is already open for another action"}));
+                break;
+            }
             if let Err(error) = crate::type_panels_ui::open_spelling(app, p.get("allLayers").and_then(Value::as_bool).unwrap_or(true)) {
                 failed = Some(json!({"step": i, "id": id, "error": error}));
                 break;
diff --git a/crates/ui-egui/src/panels/actions/tests.rs b/crates/ui-egui/src/panels/actions/tests.rs
index 6049cdb5ad..dadb5efa01 100644
--- a/crates/ui-egui/src/panels/actions/tests.rs
+++ b/crates/ui-egui/src/panels/actions/tests.rs
@@ -1413,6 +1413,32 @@ fn a_check_spelling_step_with_its_dialog_opens_it_and_done_continues() {
     assert_eq!(texts, ["Teh cat"]);
 }
 
+#[test]
+fn check_spelling_opened_again_while_an_action_waits_keeps_its_continuation() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let mut a = Action::new("Spell", vec![("edit.checkSpelling".into(), json!({"allLayers": false})), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["paused"]["dialog"], crate::type_panels_ui::SPELLING, "{v}");
+    let token = app.ui.type_panels.spell.as_ref().and_then(|d| d.resume);
+    assert!(token.is_some());
+    // Edit › Check Spelling… while the action waits.
+    crate::type_panels_ui::open_spelling(&mut app, true).unwrap();
+    assert_eq!(app.ui.type_panels.spell.as_ref().and_then(|d| d.resume), token, "the reopened dialog keeps the token");
+    // A second playback that reaches a Check Spelling step with its dialog fails there.
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["failed"]["step"], 0, "{v}");
+    assert_eq!(app.ui.type_panels.spell.as_ref().and_then(|d| d.resume), token, "the waiting action keeps the dialog");
+    assert!(!layer_names(&app).contains(&"after".to_string()));
+    crate::type_panels_ui::close_spelling(&mut app);
+    let after = layer_names(&app).iter().filter(|n| *n == "after").count();
+    assert_eq!(after, 1, "Done continued the waiting action once");
+    assert!(app.paused_playbacks.paused.is_empty());
+}
+
 #[test]
 fn a_dialog_toggled_step_pauses_playback_and_resumes_on_ok() {
     let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
diff --git a/crates/ui-egui/src/panels/type_panels_ui.rs b/crates/ui-egui/src/panels/type_panels_ui.rs
index dbcb140788..704b96b7dd 100644
--- a/crates/ui-egui/src/panels/type_panels_ui.rs
+++ b/crates/ui-egui/src/panels/type_panels_ui.rs
@@ -773,10 +773,12 @@ fn refresh_spelling(app: &mut PhotocraftApp) {
     }
 }
 
-/// Opens Edit › Check Spelling (returns the misspellings).
+/// Opens Edit › Check Spelling (returns the misspellings). Opening it again while an action waits
+/// at a Check Spelling step keeps that action's token, so Done still continues it.
 pub fn open_spelling(app: &mut PhotocraftApp, all_layers: bool) -> Result<Value, String> {
     app.session.execute("edit.checkSpelling", json!({ "action": "list", "allLayers": all_layers })).map_err(|e| e.to_string())?;
-    app.ui.type_panels.spell = Some(SpellDialog { all_layers, ..Default::default() });
+    let resume = app.ui.type_panels.spell.as_ref().and_then(|d| d.resume);
+    app.ui.type_panels.spell = Some(SpellDialog { all_layers, resume, ..Default::default() });
     refresh_spelling(app);
     let d = app.ui.type_panels.spell.as_ref().map(|d| d.items.clone()).unwrap_or_default();
     Ok(json!({ "dialog": SPELLING, "misspellings": d }))

From 3746a341e496bde2b96818b7136396b9c6727b1b Mon Sep 17 00:00:00 2001
From: yoriswind <yoriswind@yahoo.com>
Date: Sun, 1 Nov 2026 18:34:08 -0800
Subject: [PATCH 040/109] Preserve implicit white Artboard backgrounds in
 actions

---
 .../engine/src/cmd/atn_cmds/steps_artboard.rs   |  3 +++
 crates/engine/src/cmd/atn_cmds/tests.rs         |  4 ++--
 crates/engine/tests/it/atn_newer_events.rs      | 17 +++++++++++++++++
 docs/atn.md                                     |  1 +
 4 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
index b03adcffc2..de7b7be9e3 100644
--- a/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
+++ b/crates/engine/src/cmd/atn_cmds/steps_artboard.rs
@@ -99,6 +99,9 @@ pub(super) fn artboard_to(_: &str, p: &Value) -> Option<Descriptor> {
     }
     let mut settings = p.clone();
     let fields = settings.as_object_mut()?;
+    if !fields.contains_key("color") && fields.get("background").and_then(Value::as_str) == Some("custom") {
+        fields.insert("background".into(), json!("white"));
+    }
     let background = if fields.contains_key("color") { "custom" } else { "white" };
     // Native custom-without-color means white. Other types ignore this last-used color.
     for (key, value) in [("background", json!(background)), ("color", json!([1.0, 1.0, 1.0])), ("preset", json!("")), ("guideIDs", json!([]))] {
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index 19e269a14c..91566906db 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -738,10 +738,10 @@ fn every_mapped_command_exports_and_imports_back() {
         }
     }
     // Partial native backgrounds need no recorded preset, guide IDs or last-used color.
-    for background in ["white", "black", "transparent", "custom"] {
+    for (background, imported_background) in [("white", "white"), ("black", "black"), ("transparent", "transparent"), ("custom", "white")] {
         let item = export_item("layer.new.artboardFromGroup", &json!({"background":background}), "S").unwrap();
         let Mapped::Steps(steps) = (event_for(&item.event).unwrap().from)(item.descriptor.as_ref().unwrap()) else { panic!("Artboard did not import") };
-        assert_eq!(steps, [("layer.new.artboardFromGroup".into(), json!({"background":background,"color":[1.0,1.0,1.0],"preset":"","guideIDs":[]}))]);
+        assert_eq!(steps, [("layer.new.artboardFromGroup".into(), json!({"background":imported_background,"color":[1.0,1.0,1.0],"preset":"","guideIDs":[]}))]);
         assert_eq!(export_item(&steps[0].0, &steps[0].1, "S").unwrap().descriptor, item.descriptor);
     }
     // Every command the table claims to export has a case above.
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 55f6149f55..e864751340 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -549,6 +549,23 @@ fn artboard_from_group_replaces_the_previous_layer_selection() {
     assert!(s.active().unwrap().doc.layer(group).is_none());
 }
 
+/// A missing custom color means White; an explicit white color remains Custom through save/load.
+#[test]
+fn artboard_partial_custom_background_preserves_the_document_variant() {
+    for params in [json!({"background":"custom"}), json!({"background":"custom","color":[1,1,1]})] {
+        let mut s = artboard_fixture();
+        s.execute("layer.new.artboardFromGroup", params.clone()).unwrap();
+        let expected = s.active().unwrap().doc.clone();
+        assert!(s.undo());
+        let action = Action::new("A", vec![("layer.new.artboardFromGroup".into(), params)]);
+        let (bytes, skipped) = atn_cmds::export("Links", &[&action], &[], false).unwrap();
+        assert!(skipped.is_empty());
+        assert_eq!(load(&mut s, &bytes)["unsupported"], json!([]));
+        play(&mut s);
+        assert_eq!(s.active().unwrap().doc, expected);
+    }
+}
+
 /// Preserve fractional wire values exactly while playback uses normalized native RGB.
 #[test]
 fn artboard_fractional_colors_survive_import_save_and_playback() {
diff --git a/docs/atn.md b/docs/atn.md
index 9d12d25bd2..a4f3cd72f0 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -442,6 +442,7 @@ commands record).
 - The artboard takes the group's bounds; `Clr ` is stored on the artboard as given even when the type is 1..3.
 - PhotoCraft preserves fractional recorded RGB values exactly. Native actions with partial settings export an empty preset and guide list when absent.
   An absent native color exports as white: it matches the native custom-color fallback and is visually ignored for white, black and transparent backgrounds.
+  A custom background without a color uses the White variant (type 1); an explicit custom white color keeps type 4.
   This is canonical export metadata, not a claim about the reference application's remembered color. Imported steps retain their recorded color instead.
 
 ## Measured through dialogs and recordings

From 03799b62bce219e6f6e80fd48ec79f117ea783a1 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Sun, 1 Nov 2026 23:54:42 -0600
Subject: [PATCH 041/109] Keep recorded layer targets portable across documents

---
 crates/engine/src/actions_record.rs       | 13 +++----
 crates/engine/src/actions_record/tests.rs | 43 +++++++++++++++++++++++
 crates/engine/src/cmd/artboard_cmds.rs    | 12 ++-----
 crates/engine/src/cmd/frame_cmds.rs       |  5 +--
 crates/engine/src/cmd/type_cmds.rs        |  5 +--
 crates/engine/src/cmd/type_styles_cmds.rs | 16 ++++-----
 crates/engine/src/cmd/warp_cmds.rs        |  5 +--
 crates/engine/src/lib.rs                  |  2 +-
 docs/control-protocol.md                  |  2 +-
 docs/scorecard.md                         |  4 +--
 scorecard/automation.toml                 |  4 +--
 11 files changed, 70 insertions(+), 41 deletions(-)

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
index b257caeaf8..ed7c77f1b8 100644
--- a/crates/engine/src/actions_record.rs
+++ b/crates/engine/src/actions_record.rs
@@ -18,7 +18,7 @@
 
 use std::sync::Arc;
 
-use photocraft_doc::{Document, LayerContent, LayerId};
+use photocraft_doc::{DocId, Document, LayerContent, LayerId};
 use serde_json::Value;
 
 use crate::Session;
@@ -63,10 +63,11 @@ pub(crate) fn portable(id: &str, mut params: Value, before: &Before) -> Value {
 /// The text layer a journaled `type.create` made or `type.edit` changed, so the keystrokes that
 /// follow fold into that entry only when they type into the same layer (the Type tool selects
 /// a clicked layer without a command, so the journal alone cannot tell).
-pub(crate) fn typed_layer(s: &Session, id: &str, params: &Value) -> Option<LayerId> {
+pub(crate) fn typed_layer(s: &Session, id: &str, params: &Value) -> Option<(DocId, LayerId)> {
+    let doc_id = s.active()?.doc.id;
     match id {
-        "type.create" => s.active()?.active_layer,
-        "type.edit" => crate::commands::layer_param(s, params).ok(),
+        "type.create" => s.active()?.active_layer.map(|layer| (doc_id, layer)),
+        "type.edit" => crate::commands::layer_param(s, params).ok().map(|layer| (doc_id, layer)),
         _ => None,
     }
 }
@@ -83,7 +84,7 @@ pub(crate) enum Keystroke {
 
 /// Folds a Type-tool keystroke into the journal entry before it (see the module doc), or turns
 /// it into a whole-text step. `previous` is the layer the last entry typed into.
-pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous: Option<LayerId>) -> Keystroke {
+pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous: Option<(DocId, LayerId)>) -> Keystroke {
     if id != "type.edit" {
         return Keystroke::None;
     }
@@ -107,7 +108,7 @@ pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous
         step.insert("text".into(), Value::String(text.clone()));
         Keystroke::Step(Value::Object(step))
     };
-    if previous != Some(target) {
+    if previous != s.active().map(|st| (st.doc.id, target)) {
         return whole();
     }
     // A new recording starts at a journal boundary. Its first edit cannot change an entry
diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index 316ca072b0..dc6efb5f69 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -158,6 +158,25 @@ fn keystrokes_into_another_layer_do_not_fold() {
     assert!(last(&s).1["layer"].is_string() && last(&s).1.get("replace").is_some(), "{}", last(&s).1);
 }
 
+#[test]
+fn keystrokes_in_another_document_do_not_fold_into_the_previous_document() {
+    let mut s = session();
+    let first = s.execute("type.create", json!({"x": 2, "y": 20, "text": "A", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let mut copy = s.active().unwrap().doc.as_ref().clone();
+    if let Some(layer) = copy.layer_mut(LayerId(first))
+        && let photocraft_doc::LayerContent::Text(text) = &mut layer.content
+    {
+        text.text = "B".into();
+    }
+    s.add_document(copy, None);
+    let second = first;
+    let before = s.journal.len();
+    s.execute("type.edit", json!({"layer": second, "replace": {"start": 1, "end": 1, "text": "!"}, "coalesce": "typing"})).unwrap();
+    assert_eq!(s.journal.len(), before + 1, "typing in a different document needs a new journal step");
+    assert_eq!(s.journal[before - 1].1["text"], "A");
+    assert_eq!(last(&s).1["text"], "B!");
+}
+
 #[test]
 fn a_recording_replays_on_a_document_with_other_layer_ids() {
     let mut s = session();
@@ -193,3 +212,27 @@ fn a_recording_replays_on_a_document_with_other_layer_ids() {
     assert_eq!(text.as_deref(), Some("Hi"), "the typed text replayed as one step");
     assert!(s.documents()[0].doc.layer(LayerId(bg)).is_some());
 }
+
+#[test]
+fn recorded_edit_targets_a_named_nonactive_type_layer_on_another_document() {
+    let mut s = session();
+    let first = s.execute("type.create", json!({"x": 2, "y": 20, "text": "Old", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    s.execute("layer.setProps", json!({"layer": first, "name": "Caption"})).unwrap();
+    new_layer(&mut s, "Top");
+    s.execute("actions.record", json!({"name": "Edit caption"})).unwrap();
+    s.execute("type.edit", json!({"layer": first, "text": "New"})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Edit caption"})).unwrap()["steps"].clone();
+    assert_eq!(steps, json!([["type.edit", {"layer": "Caption", "text": "New"}]]));
+
+    s.execute("file.new", json!({"width": 32, "height": 32})).unwrap();
+    let second = s.execute("type.create", json!({"x": 2, "y": 20, "text": "Other", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    s.execute("layer.setProps", json!({"layer": second, "name": "Caption"})).unwrap();
+    new_layer(&mut s, "Top");
+    assert_ne!(first, second);
+    let played = s.execute("actions.play", json!({"action": "Edit caption"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    let layer = s.active().unwrap().doc.layer(LayerId(second)).unwrap();
+    let photocraft_doc::LayerContent::Text(text) = &layer.content else { panic!("expected type layer") };
+    assert_eq!(text.text, "New");
+}
diff --git a/crates/engine/src/cmd/artboard_cmds.rs b/crates/engine/src/cmd/artboard_cmds.rs
index 2f05ddfae0..0ad2bc2f92 100644
--- a/crates/engine/src/cmd/artboard_cmds.rs
+++ b/crates/engine/src/cmd/artboard_cmds.rs
@@ -303,7 +303,7 @@ fn new_artboard(s: &mut Session, p: &Value) -> Result<Value> {
 
 fn artboard_from_group(s: &mut Session, p: &Value) -> Result<Value> {
     let d = s.active().ok_or(EngineError::NoDocument)?;
-    let id = p.get("layer").and_then(Value::as_u64).map(LayerId).or(d.active_layer).ok_or(EngineError::Other("no active layer".into()))?;
+    let id = crate::commands::layer_param(s, p)?;
     let canvas = d.doc.bounds();
     let background = background_param(p, "layer.new.artboardFromGroup")?.unwrap_or_default();
     let rect = s.edit("Artboard from Group", |doc, active| {
@@ -377,10 +377,7 @@ fn artboard_from_layers(s: &mut Session, p: &Value) -> Result<Value> {
 fn set_props(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "layer.artboard.set";
     let d = s.active().ok_or(EngineError::NoDocument)?;
-    let id = match p.get("layer").and_then(Value::as_u64) {
-        Some(v) => LayerId(v),
-        None => active_artboard(s).ok_or_else(|| bad(cmd, "no artboard selected"))?,
-    };
+    let id = crate::commands::explicit_layer(s, p)?.or_else(|| active_artboard(s)).ok_or_else(|| bad(cmd, "no artboard selected"))?;
     let old = d.doc.layer(id).and_then(Layer::artboard).cloned().ok_or_else(|| bad(cmd, "the layer is not an artboard"))?;
     let preset = p.get("preset").and_then(Value::as_str).map(str::to_string);
     let mut base = xywh(old.rect);
@@ -441,10 +438,7 @@ fn set_props(s: &mut Session, p: &Value) -> Result<Value> {
 fn add_beside(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "layer.artboard.addBeside";
     let d = s.active().ok_or(EngineError::NoDocument)?;
-    let id = match p.get("layer").and_then(Value::as_u64) {
-        Some(v) => LayerId(v),
-        None => active_artboard(s).ok_or_else(|| bad(cmd, "no artboard selected"))?,
-    };
+    let id = crate::commands::explicit_layer(s, p)?.or_else(|| active_artboard(s)).ok_or_else(|| bad(cmd, "no artboard selected"))?;
     let src = d.doc.layer(id).and_then(Layer::artboard).cloned().ok_or_else(|| bad(cmd, "the layer is not an artboard"))?;
     let side = p.get("side").and_then(Value::as_str).unwrap_or("right");
     let duplicate = p.get("duplicate").and_then(Value::as_bool).unwrap_or(false);
diff --git a/crates/engine/src/cmd/frame_cmds.rs b/crates/engine/src/cmd/frame_cmds.rs
index c2cd6283a7..9bfcb257de 100644
--- a/crates/engine/src/cmd/frame_cmds.rs
+++ b/crates/engine/src/cmd/frame_cmds.rs
@@ -124,10 +124,7 @@ fn new_frame(s: &mut Session, p: &Value) -> Result<Value> {
         Some(Some("ellipse")) => true,
         Some(_) => return Err(bad("`shape` must be \"rectangle\" or \"ellipse\"".into())),
     };
-    let content = match p.get("layer") {
-        None | Some(Value::Null) => None,
-        Some(v) => Some(LayerId(v.as_u64().ok_or_else(|| bad(format!("`layer` = {v} is not a layer id")))?)),
-    };
+    let content = crate::commands::explicit_layer(s, p)?;
     let name = p.get("name").and_then(Value::as_str).map(str::to_string);
     let gid = s.edit("New Frame", |doc, active| {
         let mask =
diff --git a/crates/engine/src/cmd/type_cmds.rs b/crates/engine/src/cmd/type_cmds.rs
index 58a2145409..6206a17fc9 100644
--- a/crates/engine/src/cmd/type_cmds.rs
+++ b/crates/engine/src/cmd/type_cmds.rs
@@ -24,10 +24,7 @@ fn has_doc(s: &Session) -> std::result::Result<(), String> {
 }
 
 fn layer_id(s: &Session, p: &Value) -> Result<LayerId> {
-    match p.get("layer").and_then(Value::as_u64) {
-        Some(id) => Ok(LayerId(id)),
-        None => s.active().and_then(|d| d.active_layer).ok_or(EngineError::Other("no active layer".into())),
-    }
+    crate::commands::layer_param(s, p)
 }
 
 fn bad(cmd: &str, msg: impl Into<String>) -> EngineError {
diff --git a/crates/engine/src/cmd/type_styles_cmds.rs b/crates/engine/src/cmd/type_styles_cmds.rs
index 7fc58a5ec4..33c91f079b 100644
--- a/crates/engine/src/cmd/type_styles_cmds.rs
+++ b/crates/engine/src/cmd/type_styles_cmds.rs
@@ -42,21 +42,21 @@ fn text_of(doc: &Document, id: LayerId) -> Option<&TextLayer> {
 }
 
 /// Type layers a style command acts on: `layer`, `layers`, else the selected type layers.
-fn targets(s: &Session, p: &Value) -> Vec<LayerId> {
-    let Some(st) = s.active() else { return Vec::new() };
-    let ids: Vec<LayerId> = if let Some(id) = p.get("layer").and_then(Value::as_u64) {
-        vec![LayerId(id)]
+fn targets(s: &Session, p: &Value) -> Result<Vec<LayerId>> {
+    let Some(st) = s.active() else { return Ok(Vec::new()) };
+    let ids: Vec<LayerId> = if let Some(id) = crate::commands::explicit_layer(s, p)? {
+        vec![id]
     } else if let Some(a) = p.get("layers").and_then(Value::as_array) {
         a.iter().filter_map(Value::as_u64).map(LayerId).collect()
     } else {
         st.selected_layers()
     };
-    ids.into_iter().filter(|id| text_of(&st.doc, *id).is_some()).collect()
+    Ok(ids.into_iter().filter(|id| text_of(&st.doc, *id).is_some()).collect())
 }
 
 fn has_target(s: &Session) -> std::result::Result<(), String> {
     has_doc(s)?;
-    if targets(s, &Value::Null).is_empty() { Err("select a type layer".into()) } else { Ok(()) }
+    if targets(s, &Value::Null).is_ok_and(|targets| !targets.is_empty()) { Ok(()) } else { Err("select a type layer".into()) }
 }
 
 fn byte_at(text: &str, ci: usize) -> usize {
@@ -317,7 +317,7 @@ type Target = (LayerId, Option<(usize, usize)>);
 /// Target list with byte ranges (`range` applies only to a single layer).
 fn target_ranges(s: &Session, p: &Value) -> Result<Vec<Target>> {
     let st = s.active().ok_or(EngineError::NoDocument)?;
-    let ids = targets(s, p);
+    let ids = targets(s, p)?;
     if ids.is_empty() {
         return Err(EngineError::Other("no type layer to apply the style to".into()));
     }
@@ -334,7 +334,7 @@ fn target_ranges(s: &Session, p: &Value) -> Result<Vec<Target>> {
 /// run's byte range.
 fn sample(s: &Session, p: &Value) -> Option<(CharStyle, ParagraphStyle, LayerId, (usize, usize))> {
     let st = s.active()?;
-    let id = *targets(s, p).first()?;
+    let id = *targets(s, p).ok()?.first()?;
     let t = text_of(&st.doc, id)?;
     let (a, _) = range_of(&t.text, p);
     let mut at = 0;
diff --git a/crates/engine/src/cmd/warp_cmds.rs b/crates/engine/src/cmd/warp_cmds.rs
index c5c04132d5..c2f434fb1e 100644
--- a/crates/engine/src/cmd/warp_cmds.rs
+++ b/crates/engine/src/cmd/warp_cmds.rs
@@ -362,10 +362,7 @@ const MAX_WARP_SIDE: u32 = 100_000;
 
 fn target(s: &Session, cmd: &str, p: &Value) -> Result<(LayerId, Rect)> {
     let st = s.active().ok_or(EngineError::NoDocument)?;
-    let id = match p.get("layer").and_then(Value::as_u64) {
-        Some(v) => LayerId(v),
-        None => st.active_layer.ok_or(EngineError::Other("no active layer".into()))?,
-    };
+    let id = crate::commands::layer_param(s, p)?;
     let layer = st.doc.layer(id).ok_or(EngineError::NoLayer(id))?;
     let rect = match p.get("rect").and_then(Value::as_array) {
         Some(r) if r.len() == 4 => {
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index e42929d145..4423f0fbc8 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -200,7 +200,7 @@ pub struct Session {
     /// Log of executed commands (for action recording and debugging).
     pub journal: Vec<(String, Value)>,
     /// Text layer changed by the last journal entry, for folding Type tool keystrokes.
-    typed_layer: Option<LayerId>,
+    typed_layer: Option<(photocraft_doc::DocId, LayerId)>,
     /// Coalescing key of the command being executed.
     coalesce_request: Option<String>,
     /// Pixels copied with Edit › Copy / Cut (shared by all documents, like Photoshop).
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index a8e30ee03b..a7bb6a5f80 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped, other layers are named when unique (`layer.select` included), and Type tool keystrokes fold into a whole-text `type.create`/`type.edit` step. Ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped; other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes fold into a whole-text `type.create`/`type.edit` step within the same document and layer. Ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index 81c9222a81..503cb419fa 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -11,7 +11,7 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
 | [Tools](#tools) | 36 | 9 | 0 |  |
 | [Workspace and UI](#workspace-and-ui) | 15 | 6 | 2 | settings that do nothing: 11 of 183 (target 0) |
 | [Type](#type) | 5 | 5 | 0 |  |
-| [Automation](#automation) | 6 | 2 | 3 | 631 of 631 menu items live (100.0%) |
+| [Automation](#automation) | 5 | 3 | 3 | 631 of 631 menu items live (100.0%) |
 | [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 30 of 30 crates; panic_hunt present |
 | [Distribution](#distribution) | 5 | 5 | 1 |  |
 | [Open bugs](#open-bugs) | 31 | 1 | 0 |  |
@@ -255,7 +255,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | Id | Target | Status | Issue | Note |
 |---|---|---|---|---|
 | AUTO-1 | Every menu item dispatches a command id (UI, CLI, control channel and MCP share them) | done |  | docs/parity-checklist.md: all menu items live; menus.rs is_live |
-| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_record.rs: the active layer's id is dropped, other layers are journaled by name (layer.select always), Type tool keystrokes fold into one type.create/type.edit with the whole text; replay test on a document with other layer ids |
+| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | partial | [#219](https://github.com/storytold/photocraft/issues/219) | actions_record.rs: active layer ids are dropped, uniquely named layers replay by name, and Type tool keystrokes fold per document and layer; full coverage of all numeric-only command receivers and ambiguous layer names is still open |
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index b356485c9c..f5d8c09208 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -14,9 +14,9 @@ note = "docs/parity-checklist.md: all menu items live; menus.rs is_live"
 [[item]]
 id = "AUTO-219-1"
 target = "Record actions in a document-independent form (implicit layer, merged type keystrokes)"
-status = "done"
+status = "partial"
 issue = 219
-note = "actions_record.rs: the active layer's id is dropped, other layers are journaled by name (layer.select always), Type tool keystrokes fold into one type.create/type.edit with the whole text; replay test on a document with other layer ids"
+note = "actions_record.rs: active layer ids are dropped, uniquely named layers replay by name, and Type tool keystrokes fold per document and layer; full coverage of all numeric-only command receivers and ambiguous layer names is still open"
 
 [[item]]
 id = "AUTO-219-2"

From 85cb54025cdb421e8a811aa756d317ef80b6967c Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Sun, 1 Nov 2026 23:56:10 -0600
Subject: [PATCH 042/109] Guard Batch outputs and preserve partial results

---
 apps/photocraft-cli/src/batch.rs              |  6 +-
 apps/photocraft-cli/tests/it/cli.rs           | 27 ++++++
 .../engine/src/cmd/file_cmds/batch_naming.rs  |  4 +-
 crates/engine/src/cmd/file_cmds/batch_run.rs  | 64 ++++++-------
 crates/engine/src/cmd/file_cmds/paths.rs      | 71 ++++++++------
 crates/engine/src/cmd/file_cmds/tests.rs      | 95 +++++++++++++++++++
 crates/engine/src/jobs.rs                     | 13 ++-
 crates/engine/src/jobs/tests.rs               | 26 +++++
 docs/batch-naming.md                          |  4 +-
 docs/control-protocol.md                      |  2 +-
 10 files changed, 243 insertions(+), 69 deletions(-)

diff --git a/apps/photocraft-cli/src/batch.rs b/apps/photocraft-cli/src/batch.rs
index d2f35c57e4..15abd8848c 100644
--- a/apps/photocraft-cli/src/batch.rs
+++ b/apps/photocraft-cli/src/batch.rs
@@ -66,8 +66,10 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     } else {
         std::fs::read_dir(in_dir)
             .map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?
-            .flatten()
-            .map(|entry| entry.path())
+            .map(|entry| entry.map(|entry| entry.path()))
+            .collect::<std::io::Result<Vec<_>>>()
+            .map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?
+            .into_iter()
             .filter(|path| is_input(path))
             .map(|path| photocraft_engine::file_cmds::BatchInput { path: path.to_string_lossy().into_owned(), rel_dir: String::new() })
             .collect()
diff --git a/apps/photocraft-cli/tests/it/cli.rs b/apps/photocraft-cli/tests/it/cli.rs
index 2981db84c6..5d7b597134 100644
--- a/apps/photocraft-cli/tests/it/cli.rs
+++ b/apps/photocraft-cli/tests/it/cli.rs
@@ -847,6 +847,33 @@ fn batch_refuses_to_write_over_its_inputs() {
     assert!(after.iter().zip(&before).all(|(a, b)| a.0 == b.0 && a.1 != b.1), "both inputs replaced");
 }
 
+#[test]
+fn batch_naming_rejects_unread_input_alias_through_a_missing_directory() {
+    let d = tmp("batch-missing-directory-alias");
+    let input = d.join("in");
+    std::fs::create_dir_all(&input).unwrap();
+    write_png(&input.join("a.png"), 8, 4, 3);
+    write_png(&input.join("b.png"), 8, 4, 7);
+    let original = std::fs::read(input.join("b.png")).unwrap();
+    let actions = d.join("actions.json");
+    std::fs::write(&actions, r#"[{"command":"image.adjustments.invert"}]"#).unwrap();
+    let output = bin()
+        .arg("batch")
+        .arg("--actions")
+        .arg(&actions)
+        .arg("--in")
+        .arg(&input)
+        .arg("--out")
+        .arg(input.join("missing/.."))
+        .args(["--in-place", "--naming", "b.{ext}"])
+        .output()
+        .unwrap();
+    assert!(!output.status.success(), "{}", String::from_utf8_lossy(&output.stdout));
+    assert!(String::from_utf8_lossy(&output.stderr).contains("replace an input"));
+    assert_eq!(std::fs::read(input.join("b.png")).unwrap(), original);
+    assert!(!input.join("missing").exists());
+}
+
 /// #7437: `convert` to its own input file, however the output is spelt, is refused before
 /// anything is read or written, unless `--in-place` asks for it (as `batch` does, #492).
 #[test]
diff --git a/crates/engine/src/cmd/file_cmds/batch_naming.rs b/crates/engine/src/cmd/file_cmds/batch_naming.rs
index 706930b9c5..8d6bfba083 100644
--- a/crates/engine/src/cmd/file_cmds/batch_naming.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_naming.rs
@@ -183,7 +183,9 @@ pub fn plan(inputs: &[BatchInput], output: &str, format: &str, params: &Value) -
     {
         let sources: std::collections::HashSet<_> = inputs.iter().filter_map(|i| std::fs::canonicalize(&i.path).ok()).collect();
         for output in &outputs {
-            if std::fs::canonicalize(output).ok().is_some_and(|p| sources.contains(&p)) {
+            let identity = super::paths::destination_identity(std::path::Path::new(output))
+                .ok_or_else(|| bad(format!("naming output path cannot be resolved safely: {output}")))?;
+            if sources.contains(&identity) {
                 return Err(bad(format!("naming would replace an input file: {output}; choose a different destination or template")));
             }
         }
diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 52db5a0e5c..93e8da6d66 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -49,7 +49,7 @@ pub(crate) fn batch_inputs_tree(p: &Value, cmd: &str, output: &str) -> Result<Ve
 /// The images under `dir` and its subfolders: each folder's files sorted by name, then its
 /// subfolders in name order (depth first). Bounded by [`MAX_SUBFOLDER_DEPTH`] and
 /// [`MAX_SUBFOLDER_FILES`]; a folder reached twice (a symlink loop) is walked once, and `skip`
-/// (the output folder) is left out.
+/// (the output folder) is left out. An unreadable reached folder is an error.
 #[cfg(not(target_arch = "wasm32"))]
 pub fn list_images_tree(dir: &str, skip: &str, cmd: &str) -> Result<Vec<BatchInput>> {
     use std::path::{Path, PathBuf};
@@ -64,12 +64,8 @@ pub fn list_images_tree(dir: &str, skip: &str, cmd: &str) -> Result<Vec<BatchInp
     let mut stack: Vec<(PathBuf, String, usize)> = vec![(root.to_path_buf(), String::new(), 0)];
     while let Some((folder, rel, depth)) = stack.pop() {
         let shown = folder.to_string_lossy().into_owned();
-        // The top folder must be readable; a subfolder that isn't is skipped.
-        let files = match list_images(&shown) {
-            Ok(f) => f,
-            Err(e) if depth == 0 => return Err(e),
-            Err(_) => continue,
-        };
+        // Fail before writing any output if a reached input folder cannot be read.
+        let files = list_images(&shown)?;
         if out.len().saturating_add(files.len()) > MAX_SUBFOLDER_FILES {
             return Err(EngineError::BadParams { cmd: cmd.into(), msg: format!("{dir} holds more than {MAX_SUBFOLDER_FILES} images with its subfolders") });
         }
@@ -77,17 +73,14 @@ pub fn list_images_tree(dir: &str, skip: &str, cmd: &str) -> Result<Vec<BatchInp
         if depth >= MAX_SUBFOLDER_DEPTH {
             continue;
         }
-        let Ok(rd) = std::fs::read_dir(&folder) else { continue };
-        let mut subs: Vec<(String, PathBuf)> = rd
-            .filter_map(|e| e.ok())
-            .map(|e| e.path())
-            .filter(|p| p.is_dir())
-            .filter_map(|p| Some((p.file_name()?.to_string_lossy().into_owned(), p)))
-            .collect();
+        let rd = std::fs::read_dir(&folder).map_err(|e| EngineError::Other(format!("{shown}: {e}")))?;
+        let entries = rd.collect::<std::io::Result<Vec<_>>>().map_err(|e| EngineError::Other(format!("{shown}: {e}")))?;
+        let mut subs: Vec<(String, PathBuf)> =
+            entries.into_iter().map(|e| e.path()).filter(|p| p.is_dir()).filter_map(|p| Some((p.file_name()?.to_string_lossy().into_owned(), p))).collect();
         subs.sort();
         // Pushed in reverse so the stack pops them in name order.
         for (name, sub) in subs.into_iter().rev() {
-            let Some(c) = canon(&sub) else { continue };
+            let c = canon(&sub).ok_or_else(|| EngineError::Other(format!("{}: cannot resolve the subfolder", sub.display())))?;
             if skip.as_ref() == Some(&c) || !seen.insert(c) {
                 continue;
             }
@@ -249,6 +242,10 @@ fn write_error_log(path: &str, errors: &[Value]) -> Result<()> {
     super::paths::write_file(path, body.as_bytes()).map_err(|error| EngineError::Other(format!("error log: {error}")))
 }
 
+fn error_log_failure(path: Option<&str>, errors: &[Value]) -> Option<String> {
+    path.filter(|_| !errors.is_empty()).and_then(|path| write_error_log(path, errors).err().map(|error| error.to_string()))
+}
+
 fn batch_outcome(files: Vec<String>, errors: Vec<Value>, stopped: Option<(String, Vec<String>)>, error_log: Option<&str>) -> Value {
     let logged = !errors.is_empty();
     let mut result = json!({"files": files, "errors": errors});
@@ -306,17 +303,21 @@ fn process_batch_outputs(
             }
         }
     }
-    if let Some(path) = &policy.error_log
-        && !errors.is_empty()
-    {
-        write_error_log(path, &errors)?;
+    let log_failure = error_log_failure(policy.error_log.as_deref(), &errors);
+    let cancelled = ctx.cancelled();
+    if !cancelled {
+        ctx.progress(1.0, "");
     }
-    if ctx.cancelled() {
-        return Err(EngineError::Cancelled);
-    }
-    ctx.progress(1.0, "");
     let skipped = outputs.iter().skip(done).map(|(path, _)| path.clone()).collect();
-    Ok(batch_outcome(files, errors, stopped.map(|at| (at, skipped)), policy.error_log.as_deref()))
+    let mut result = batch_outcome(files, errors, stopped.map(|at| (at, skipped)), policy.error_log.as_deref().filter(|_| log_failure.is_none()));
+    if cancelled {
+        result["cancelled"] = json!(true);
+        result["skipped"] = json!(outputs.iter().skip(done).map(|(path, _)| path).collect::<Vec<_>>());
+    }
+    if let Some(error) = log_failure {
+        result["errorLogError"] = json!(error);
+    }
+    Ok(result)
 }
 
 /// The output paths a batch run has written, so a later input whose output name matches an
@@ -554,8 +555,8 @@ fn batch_open_documents(
             let out = paths.get(index).ok_or_else(|| EngineError::Other("batch output plan is incomplete".into()))?;
             claims.check(out).map_err(EngineError::Other)?;
             let doc = match saved {
-                Some(saved) if s.active().is_none_or(|active| active.doc.id != saved.id) => saved,
-                _ => s.documents().iter().find(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?.doc.clone(),
+                Some(saved) => saved,
+                None => s.documents().iter().find(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?.doc.clone(),
             };
             save_doc(&doc, out, save)?;
             claims.record(out, name);
@@ -576,13 +577,12 @@ fn batch_open_documents(
     {
         s.set_active(position);
     }
-    if let Some(path) = &policy.error_log
-        && !errors.is_empty()
-    {
-        write_error_log(path, &errors)?;
-    }
+    let log_failure = error_log_failure(policy.error_log.as_deref(), &errors);
     let skipped = originals.iter().skip(done).map(|(_, name, _)| name.clone()).collect();
-    let mut result = batch_outcome(files, errors, stopped.map(|at| (at, skipped)), policy.error_log.as_deref());
+    let mut result = batch_outcome(files, errors, stopped.map(|at| (at, skipped)), policy.error_log.as_deref().filter(|_| log_failure.is_none()));
+    if let Some(error) = log_failure {
+        result["errorLogError"] = json!(error);
+    }
     result["documents"] = json!(originals.len());
     Ok(result)
 }
diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index 41d6121b94..63455286ec 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -40,8 +40,9 @@ pub(crate) fn write_file(path: &str, _bytes: &[u8]) -> Result<()> {
 #[cfg(not(target_arch = "wasm32"))]
 pub fn list_images(dir: &str) -> Result<Vec<String>> {
     let rd = std::fs::read_dir(dir).map_err(|e| EngineError::Other(format!("{dir}: {e}")))?;
-    let mut out: Vec<String> = rd
-        .filter_map(|e| e.ok())
+    let entries = rd.collect::<std::io::Result<Vec<_>>>().map_err(|e| EngineError::Other(format!("{dir}: {e}")))?;
+    let mut out: Vec<String> = entries
+        .into_iter()
         .map(|e| e.path())
         .filter(|p| p.is_file() && openable_name(&p.to_string_lossy()))
         .map(|p| p.to_string_lossy().into_owned())
@@ -181,6 +182,34 @@ pub fn same_file(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path::Path>)
     false
 }
 
+/// Resolve a future output path component by component. Existing symlinks are followed before
+/// applying a later `..`, while components not created yet are kept so a new `x/../file` still
+/// resolves to the file it would reach after `x` is created.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn destination_identity(path: &std::path::Path) -> Option<std::path::PathBuf> {
+    use std::path::{Component, PathBuf};
+    let absolute = if path.is_absolute() { path.to_path_buf() } else { std::env::current_dir().ok()?.join(path) };
+    let mut resolved = PathBuf::new();
+    for component in absolute.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                resolved.pop();
+            }
+            Component::Normal(_) => {
+                resolved.push(component.as_os_str());
+                match std::fs::symlink_metadata(&resolved) {
+                    Ok(_) => resolved = std::fs::canonicalize(&resolved).ok()?,
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(_) => return None,
+                }
+            }
+            Component::Prefix(_) | Component::RootDir => resolved.push(component.as_os_str()),
+        }
+    }
+    Some(resolved)
+}
+
 /// Whether two paths would name the same destination even before the file exists. This is used
 /// when a batch error log must not be allowed to replace a result that will be written later.
 pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path::Path>) -> bool {
@@ -190,36 +219,20 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
     }
     #[cfg(not(target_arch = "wasm32"))]
     {
-        use std::path::{Component, Path, PathBuf};
-        let normalize = |path: &Path| -> Option<PathBuf> {
-            let absolute = if path.is_absolute() { path.to_path_buf() } else { std::env::current_dir().ok()?.join(path) };
-            let mut clean = PathBuf::new();
-            for component in absolute.components() {
-                match component {
-                    Component::CurDir => {}
-                    Component::ParentDir => {
-                        clean.pop();
+        match (destination_identity(a), destination_identity(b)) {
+            (Some(a), Some(b)) => {
+                #[cfg(any(target_os = "windows", target_os = "macos"))]
+                {
+                    match (a.to_str(), b.to_str()) {
+                        (Some(a), Some(b)) => a.eq_ignore_ascii_case(b),
+                        _ => a == b,
                     }
-                    other => clean.push(other.as_os_str()),
+                }
+                #[cfg(not(any(target_os = "windows", target_os = "macos")))]
+                {
+                    a == b
                 }
             }
-            let mut existing = clean.as_path();
-            let mut suffix = Vec::new();
-            while !existing.exists() {
-                suffix.push(existing.file_name()?.to_os_string());
-                existing = existing.parent()?;
-            }
-            let mut resolved = std::fs::canonicalize(existing).ok()?;
-            for component in suffix.into_iter().rev() {
-                resolved.push(component);
-            }
-            Some(resolved)
-        };
-        match (normalize(a), normalize(b)) {
-            (Some(a), Some(b)) => match (a.to_str(), b.to_str()) {
-                (Some(a), Some(b)) => a.eq_ignore_ascii_case(b),
-                _ => a == b,
-            },
             _ => false,
         }
     }
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index e87eac1c69..ef9758fa53 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -64,6 +64,45 @@ fn batch_error_log_cannot_replace_an_input_or_result() {
     }
 }
 
+#[test]
+fn batch_naming_rejects_an_input_alias_through_a_missing_parent() {
+    let dir = tmp("batch-missing-parent-alias");
+    let first = png(&dir, "a.png", 8, 6, "#ff0000");
+    let second = png(&dir, "b.png", 8, 6, "#00ff00");
+    let original = std::fs::read(&second).unwrap();
+    let output = join(&dir, "missing/..");
+    let error =
+        Session::new().execute("file.automate.batch", json!({"steps": [], "input": [first, second], "output": output, "naming": "b.{ext}"})).unwrap_err();
+    assert!(error.to_string().contains("replace an input"), "{error}");
+    assert_eq!(std::fs::read(&second).unwrap(), original);
+    assert!(!std::path::Path::new(&join(&dir, "missing")).exists());
+}
+
+#[cfg(unix)]
+#[test]
+fn batch_error_log_rejects_a_symlink_parent_alias() {
+    use std::os::unix::fs::symlink;
+    let dir = tmp("batch-symlink-parent-alias");
+    let source_dir = join(&dir, "in");
+    std::fs::create_dir_all(&source_dir).unwrap();
+    let input = png(&source_dir, "result.png", 8, 6, "#ff0000");
+    let other = join(&dir, "other");
+    std::fs::create_dir_all(join(&other, "child")).unwrap();
+    symlink(join(&other, "child"), join(&dir, "link")).unwrap();
+    let output = other;
+    let log = join(&dir, "link/../result.png");
+    let error = Session::new().execute("file.automate.batch", json!({"steps": [], "input": [input], "output": output, "errorLog": log})).unwrap_err();
+    assert!(error.to_string().contains("errorLog"), "{error}");
+    assert!(!std::path::Path::new(&join(&output, "result.png")).exists());
+}
+
+#[cfg(target_os = "linux")]
+#[test]
+fn linux_distinct_case_destinations_are_not_the_same_file() {
+    let dir = tmp("batch-case-sensitive-destinations");
+    assert!(!same_destination(join(&dir, "Image.png"), join(&dir, "image.png")));
+}
+
 #[test]
 fn batch_open_source_edits_each_live_document_and_restores_the_active_one() {
     let dir = tmp("batch-open-documents");
@@ -87,6 +126,62 @@ fn batch_open_source_edits_each_live_document_and_restores_the_active_one() {
     assert!(std::path::Path::new(&join(&dir, "02_SECOND.PNG")).is_file());
 }
 
+#[test]
+fn batch_open_source_exports_the_document_at_the_save_point() {
+    let dir = tmp("batch-open-save-point");
+    let mut session = Session::new();
+    session.execute("file.new", json!({"name": "First", "width": 8, "height": 6})).unwrap();
+    session.execute("file.new", json!({"name": "Second", "width": 12, "height": 5})).unwrap();
+    let result = session
+        .execute(
+            "file.automate.batch",
+            json!({
+                "source": "open", "steps": [["document.activate", {"document": 1}], ["file.save", {}]],
+                "output": dir, "format": "png", "naming": "{name}.{ext}"
+            }),
+        )
+        .unwrap();
+    assert!(result["errors"].as_array().unwrap().is_empty(), "{result}");
+    let mut opened = Session::new();
+    opened.execute("file.openAs", json!({"path": join(&dir, "First.png"), "as": "png"})).unwrap();
+    assert_eq!(doc(&opened).size.width, 12, "the save point selected the second document");
+}
+
+#[test]
+fn batch_reports_file_failures_even_if_error_log_cannot_be_written() {
+    let dir = tmp("batch-error-log-write-fails");
+    let mut session = session(8, 6, 8);
+    let result = session
+        .execute(
+            "file.automate.batch",
+            json!({
+                "source": "open", "steps": [["layer.select", {"layer": "does not exist"}]],
+                "output": dir, "format": "png", "errorLog": dir
+            }),
+        )
+        .unwrap();
+    assert_eq!(result["files"], json!([]));
+    assert_eq!(result["errors"].as_array().map(Vec::len), Some(1), "{result}");
+    assert!(result["errorLogError"].as_str().is_some(), "{result}");
+}
+
+#[cfg(unix)]
+#[test]
+fn recursive_batch_reports_an_unreadable_subfolder() {
+    use std::os::unix::fs::PermissionsExt;
+    let dir = tmp("batch-unreadable-subfolder");
+    let sub = join(&dir, "locked");
+    std::fs::create_dir_all(&sub).unwrap();
+    png(&sub, "image.png", 8, 6, "#ff0000");
+    std::fs::set_permissions(&sub, std::fs::Permissions::from_mode(0o000)).unwrap();
+    let inaccessible = std::fs::read_dir(&sub).is_err();
+    let result = list_images_tree(&dir, "", "file.automate.batch");
+    std::fs::set_permissions(&sub, std::fs::Permissions::from_mode(0o700)).unwrap();
+    if inaccessible {
+        assert!(result.is_err(), "an inaccessible input folder must not be omitted");
+    }
+}
+
 #[test]
 fn close_all_and_close_others() {
     let mut s = session(8, 8, 8);
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index ac9e38a723..3c2cb9e3b9 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -693,10 +693,17 @@ impl Session {
         }
     }
 
-    /// Cancel job `id`: it stops at its next check, its result is discarded and the document
-    /// stays unchanged. The document is unlocked at once. False if no such job is running.
+    /// Cancel job `id`: ordinary jobs stop at their next check and discard their result.
+    /// A batch finishes the current input and reports outputs already written. False if no
+    /// such job is running.
     pub fn cancel_job(&mut self, id: JobId) -> bool {
         let Some(i) = self.jobs.running.iter().position(|r| r.id == id) else { return false };
+        // Earlier batch outputs are already on disk. Let the worker stop after its current
+        // input and return the completed and skipped lists.
+        if self.jobs.running[i].command == "file.automate.batch" {
+            self.jobs.running[i].ctx.cancel();
+            return true;
+        }
         // A print worker can already have handed the job to the OS. Discarding its result
         // would falsely report cancellation; removal belongs to the system print queue.
         if matches!(self.jobs.running[i].command.as_str(), "file.print" | "file.printOneCopy") {
@@ -977,7 +984,7 @@ impl Session {
         let outcome = match r {
             Err(EngineError::Cancelled) => JobOutcome::Cancelled,
             Err(e) => JobOutcome::Failed(e.to_string()),
-            Ok(_) if job.ctx.cancelled() => JobOutcome::Cancelled,
+            Ok(_) if job.ctx.cancelled() && job.command != "file.automate.batch" => JobOutcome::Cancelled,
             Ok(payload) => match self.apply_job(&job, apply, payload) {
                 Ok(v) => JobOutcome::Done(v),
                 Err(EngineError::Cancelled) => JobOutcome::Cancelled,
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index 0974a5c17a..19502cae35 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -543,6 +543,32 @@ fn open_runs_as_a_job_and_cancel_adds_nothing() {
     assert!(matches!(wait_event(&mut s, id).outcome, JobOutcome::Failed(_)));
 }
 
+#[test]
+fn cancelled_batch_job_returns_its_partial_result() {
+    let mut s = Session::new();
+    let id = job(s
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            |ctx| {
+                while !ctx.cancelled() {
+                    std::thread::sleep(Duration::from_millis(2));
+                }
+                Ok(json!({"files": ["done.png"], "skipped": ["later.png"], "cancelled": true}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap());
+    assert!(s.cancel_job(id));
+    let event = wait_event(&mut s, id);
+    let JobOutcome::Done(result) = &event.outcome else { panic!("batch result was discarded: {:?}", event.outcome) };
+    assert_eq!(result["files"], json!(["done.png"]));
+    assert_eq!(result["skipped"], json!(["later.png"]));
+    assert_eq!(result["cancelled"], true);
+}
+
 /// Ask When Opening: a file whose profile doesn't match is decoded but not added; the shell takes
 /// it once the prompt is answered. Without Ask it opens as usual.
 #[test]
diff --git a/docs/batch-naming.md b/docs/batch-naming.md
index d6f64e33cd..caa17e78e2 100644
--- a/docs/batch-naming.md
+++ b/docs/batch-naming.md
@@ -21,7 +21,9 @@ keeps its order. Failed inputs consume their position, so later filenames do not
 Braces in an input filename are literal text, not additional tokens. Subfolder inputs keep their
 relative folders under the output folder. **Stop On Error** leaves later inputs unprocessed;
 **Error Log** records failures and their reasons. Folder batches report progress per file and
-can be cancelled after the current file.
+can be cancelled after the current file. A cancelled batch returns `cancelled: true`, its
+completed `files`, and `skipped` inputs. If writing the error log fails, the batch still
+returns its per-file results with `errorLogError` instead of `errorLog`.
 
 Unknown tokens, unmatched braces, invalid parameter types, path separators, reserved filename
 characters, excessive filename length (255 UTF-8 bytes), and serial overflow are rejected before
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 7c5f4f2c24..b5f0dca68e 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -250,7 +250,7 @@ The shape is pinned by a test in `crates/automation/src/rpc.rs` (#3684).
 
 ### Background jobs (#210)
 
-Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
+Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged; a folder Batch can already have written earlier output files and reports those paths when cancelled. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
 
 ## Preferences
 

From 3191b89064f4c7c3fb78873857dc4cb50b1e9deb Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 00:25:07 -0600
Subject: [PATCH 043/109] Preserve styled text and explicit layers in action
 replay

---
 crates/engine/src/actions_record.rs           | 44 +++++---------
 crates/engine/src/actions_record/tests.rs     | 60 ++++++++++++++++---
 crates/engine/src/cmd/fx_visibility_cmds.rs   | 15 +++--
 .../src/cmd/layer_multi_cmds/selection.rs     |  4 ++
 crates/engine/src/cmd/type_mask_cmds.rs       | 20 +++++--
 crates/engine/src/cmd/type_styles_cmds.rs     |  3 +
 .../engine/src/cmd/type_styles_cmds/tests.rs  |  9 +++
 crates/engine/src/jobs.rs                     |  1 -
 docs/control-protocol.md                      |  2 +-
 9 files changed, 109 insertions(+), 49 deletions(-)

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
index ed7c77f1b8..f55efee176 100644
--- a/crates/engine/src/actions_record.rs
+++ b/crates/engine/src/actions_record.rs
@@ -9,10 +9,8 @@
 //! - any other `layer` id becomes the layer's name when the name is unique in the document, and
 //!   `layer.select` always does (selecting is choosing a layer by name, as Photoshop records
 //!   it); an ambiguous name keeps the id, which still replays on the recording document;
-//! - the Type tool's keystrokes (`type.edit` with `replace` and the editing session's `coalesce`
-//!   key) fold into the entry before them: the `type.create` that made the layer gets the final
-//!   text, and keystrokes in an existing layer become one `type.edit` with the whole text, as
-//!   Photoshop records "Make text layer" and "Set current text layer".
+//! - the Type tool's keystrokes fold into the `type.create` that made the layer. On an existing
+//!   layer, each replacement stays separate so replay keeps style runs between edited spans.
 //!
 //! Ids are still accepted everywhere; only what the journal keeps changes.
 
@@ -48,11 +46,12 @@ pub(crate) fn portable(id: &str, mut params: Value, before: &Before) -> Value {
     let Some(target) = params.get("layer").and_then(Value::as_u64).map(LayerId) else { return params };
     let Some(obj) = params.as_object_mut() else { return params };
     let only_selected = before.selected.len() <= 1;
-    if id != "layer.select" && before.active_layer == Some(target) && only_selected {
+    if !matches!(id, "layer.select" | "layer.new.frame") && before.active_layer == Some(target) && only_selected {
         obj.remove("layer");
         return params;
     }
     if let Some(layer) = doc.layer(target)
+        && !(id == "select.loadSelection" && (layer.name.is_empty() || layer.name == "merged"))
         && doc.walk().iter().filter(|(_, _, l)| l.name == layer.name).count() == 1
     {
         obj.insert("layer".into(), Value::String(layer.name.clone()));
@@ -78,18 +77,19 @@ pub(crate) enum Keystroke {
     None,
     /// Folded into the entry before it.
     Folded,
-    /// A new entry setting the whole text, so a later keystroke can fold into it.
-    Step(Value),
 }
 
-/// Folds a Type-tool keystroke into the journal entry before it (see the module doc), or turns
-/// it into a whole-text step. `previous` is the layer the last entry typed into.
+/// Fold a Type-tool keystroke into its creation step only. A whole-text step on an existing
+/// layer can collapse distinct style runs between separate edited spans on replay (#4514).
+/// `previous` is the layer the last entry typed into.
 pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous: Option<(DocId, LayerId)>) -> Keystroke {
     if id != "type.edit" {
         return Keystroke::None;
     }
     let Some(obj) = params.as_object() else { return Keystroke::None };
-    let Some(key) = obj.get("coalesce").and_then(Value::as_str) else { return Keystroke::None };
+    if obj.get("coalesce").and_then(Value::as_str).is_none() {
+        return Keystroke::None;
+    }
     if !obj.contains_key("replace") || !obj.keys().all(|k| matches!(k.as_str(), "layer" | "replace" | "coalesce")) {
         return Keystroke::None;
     }
@@ -101,31 +101,19 @@ pub(crate) fn fold_keystroke(s: &mut Session, id: &str, params: &Value, previous
     }) else {
         return Keystroke::None;
     };
-    let layer = obj.get("layer");
-    let whole = || {
-        let mut step = obj.clone();
-        step.remove("replace");
-        step.insert("text".into(), Value::String(text.clone()));
-        Keystroke::Step(Value::Object(step))
-    };
     if previous != s.active().map(|st| (st.doc.id, target)) {
-        return whole();
+        return Keystroke::None;
     }
     // A new recording starts at a journal boundary. Its first edit cannot change an entry
     // before that boundary, or actions.stop would miss the edit altogether.
     if s.actions.recording.is_some_and(|(start, _)| s.journal.len() <= start) {
-        return whole();
+        return Keystroke::None;
     }
-    let Some((last, lp)) = s.journal.last_mut() else { return whole() };
-    let Some(lo) = lp.as_object_mut() else { return whole() };
-    let folds = match last.as_str() {
-        "type.create" => layer.is_none(),
-        "type.edit" => lo.get("coalesce").and_then(Value::as_str) == Some(key) && lo.get("layer") == layer && lo.contains_key("text"),
-        _ => false,
-    };
-    if !folds {
-        return whole();
+    let Some((last, lp)) = s.journal.last_mut() else { return Keystroke::None };
+    if last != "type.create" || obj.contains_key("layer") {
+        return Keystroke::None;
     }
+    let Some(lo) = lp.as_object_mut() else { return Keystroke::None };
     lo.insert("text".into(), Value::String(text));
     Keystroke::Folded
 }
diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index dc6efb5f69..b769554120 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -96,6 +96,26 @@ fn a_background_job_journals_the_same_way() {
     assert_eq!(last(&s), &("filter.blur.gaussianBlur".into(), json!({"radius": 2})));
 }
 
+#[test]
+fn frame_action_keeps_the_layer_it_wraps() {
+    let mut s = session();
+    let picture = new_layer(&mut s, "Picture");
+    s.execute("actions.record", json!({"name": "Frame picture"})).unwrap();
+    s.execute("layer.new.frame", json!({"x": 1, "y": 1, "width": 20, "height": 20, "layer": picture})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Frame picture"})).unwrap()["steps"].clone();
+    assert_eq!(steps[0][1]["layer"], "Picture", "the frame must wrap the recorded source layer");
+}
+
+#[test]
+fn merged_named_layer_keeps_its_id_as_a_selection_source() {
+    let mut s = session();
+    let source = new_layer(&mut s, "merged");
+    new_layer(&mut s, "Top");
+    s.execute("select.loadSelection", json!({"channel": "transparency", "layer": source})).unwrap();
+    assert_eq!(last(&s).1["layer"], source, "the reserved name must not mean the merged document");
+}
+
 #[test]
 fn keystrokes_fold_into_the_type_layer_they_made() {
     let mut s = session();
@@ -115,19 +135,43 @@ fn keystrokes_fold_into_the_type_layer_they_made() {
 }
 
 #[test]
-fn keystrokes_in_an_existing_layer_become_one_edit() {
+fn keystrokes_in_an_existing_layer_keep_separate_replacements() {
     let mut s = session();
     let id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "Hi", "size": 12})).unwrap()["layer"].as_u64().unwrap();
     s.execute("layer.setProps", json!({"opacity": 0.9})).unwrap();
     let n = s.journal.len();
     s.execute("type.edit", json!({"layer": id, "replace": {"start": 2, "end": 2, "text": "!"}, "coalesce": "t2"})).unwrap();
     s.execute("type.edit", json!({"layer": id, "replace": {"start": 0, "end": 1, "text": "h"}, "coalesce": "t2"})).unwrap();
-    assert_eq!(s.journal.len(), n + 1);
-    assert_eq!(last(&s), &("type.edit".into(), json!({"text": "hi!", "coalesce": "t2"})));
+    assert_eq!(s.journal.len(), n + 2);
+    assert_eq!(s.journal[n].1, json!({"replace": {"start": 2, "end": 2, "text": "!"}, "coalesce": "t2"}));
+    assert_eq!(last(&s).1, json!({"replace": {"start": 0, "end": 1, "text": "h"}, "coalesce": "t2"}));
     // A new editing session starts a new step.
     s.execute("type.edit", json!({"layer": id, "replace": {"start": 3, "end": 3, "text": "?"}, "coalesce": "t3"})).unwrap();
-    assert_eq!(s.journal.len(), n + 2);
-    assert_eq!(last(&s).1, json!({"text": "hi!?", "coalesce": "t3"}));
+    assert_eq!(s.journal.len(), n + 3);
+    assert_eq!(last(&s).1, json!({"replace": {"start": 3, "end": 3, "text": "?"}, "coalesce": "t3"}));
+}
+
+#[test]
+fn action_replay_preserves_styles_between_separate_typing_edits() {
+    let mut s = session();
+    let id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "a M z", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    s.execute("type.edit", json!({"layer": id, "runs": [{"start": 2, "end": 3, "size": 24}]})).unwrap();
+    let replay = s.active().unwrap().doc.as_ref().clone();
+    s.execute("actions.record", json!({"name": "Two typed edits"})).unwrap();
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 0, "end": 1, "text": "A"}, "coalesce": "typing"})).unwrap();
+    s.execute("type.edit", json!({"layer": id, "replace": {"start": 4, "end": 5, "text": "Z"}, "coalesce": "typing"})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let original = s.active().unwrap().doc.layer(LayerId(id)).unwrap();
+    let photocraft_doc::LayerContent::Text(original) = &original.content else { panic!("type layer") };
+    let original = original.clone();
+    assert_eq!(original.text, "A M Z");
+    s.add_document(replay, None);
+    let played = s.execute("actions.play", json!({"action": "Two typed edits"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    let copy = s.active().unwrap().doc.layer(LayerId(id)).unwrap();
+    let photocraft_doc::LayerContent::Text(copy) = &copy.content else { panic!("type layer") };
+    assert_eq!(copy.text, original.text);
+    assert_eq!(copy.char_runs(), original.char_runs(), "the unchanged middle run keeps its style");
 }
 
 #[test]
@@ -138,7 +182,7 @@ fn recording_does_not_fold_into_a_step_from_before_recording_started() {
     s.execute("type.edit", json!({"layer": id, "replace": {"start": 2, "end": 2, "text": "!"}, "coalesce": "t2"})).unwrap();
     s.execute("actions.stop", json!({})).unwrap();
     let steps = s.execute("actions.get", json!({"action": "Type more"})).unwrap()["steps"].clone();
-    assert_eq!(steps, json!([["type.edit", {"text": "Hi!", "coalesce": "t2"}]]));
+    assert_eq!(steps, json!([["type.edit", {"replace": {"start": 2, "end": 2, "text": "!"}, "coalesce": "t2"}]]));
 }
 
 #[test]
@@ -151,7 +195,7 @@ fn keystrokes_into_another_layer_do_not_fold() {
     let n = s.journal.len();
     s.execute("type.edit", json!({"layer": first, "replace": {"start": 3, "end": 3, "text": "!"}, "coalesce": "t4"})).unwrap();
     assert_eq!(s.journal.len(), n + 1, "typing into the first layer is its own step");
-    assert_eq!(last(&s).1, json!({"text": "One!", "coalesce": "t4"}));
+    assert_eq!(last(&s).1, json!({"replace": {"start": 3, "end": 3, "text": "!"}, "coalesce": "t4"}));
     assert_eq!(s.journal[n - 1].1["text"], "", "the second Make Type Layer keeps its own text");
     // Programmatic edits (no session key) and other edits stand on their own.
     s.execute("type.edit", json!({"layer": second, "replace": {"start": 0, "end": 0, "text": "x"}})).unwrap();
@@ -174,7 +218,7 @@ fn keystrokes_in_another_document_do_not_fold_into_the_previous_document() {
     s.execute("type.edit", json!({"layer": second, "replace": {"start": 1, "end": 1, "text": "!"}, "coalesce": "typing"})).unwrap();
     assert_eq!(s.journal.len(), before + 1, "typing in a different document needs a new journal step");
     assert_eq!(s.journal[before - 1].1["text"], "A");
-    assert_eq!(last(&s).1["text"], "B!");
+    assert_eq!(last(&s).1["replace"], json!({"start": 1, "end": 1, "text": "!"}));
 }
 
 #[test]
diff --git a/crates/engine/src/cmd/fx_visibility_cmds.rs b/crates/engine/src/cmd/fx_visibility_cmds.rs
index 7911bcd3cc..ba121f7f3c 100644
--- a/crates/engine/src/cmd/fx_visibility_cmds.rs
+++ b/crates/engine/src/cmd/fx_visibility_cmds.rs
@@ -2,7 +2,6 @@
 //! hides every effect of that layer; the eye on one effect's row shows or hides that effect. The
 //! effects keep their settings either way, and each toggle is one history step.
 
-use photocraft_doc::LayerId;
 use serde_json::{Value, json};
 
 use crate::commands::CommandSpec;
@@ -32,10 +31,7 @@ fn set_visible(s: &mut Session, p: &Value) -> Result<Value> {
         Some(v) => Some(v.as_u64().and_then(|i| usize::try_from(i).ok()).ok_or_else(|| bad("`index` must be an effect position (0, 1, …)"))?),
     };
     let st = s.active().ok_or(EngineError::NoDocument)?;
-    let id = match p.get("layer") {
-        None | Some(Value::Null) => st.active_layer.ok_or_else(|| bad("no layer given and no active layer"))?,
-        Some(v) => LayerId(v.as_u64().ok_or_else(|| bad("`layer` must be a layer id"))?),
-    };
+    let id = crate::commands::explicit_layer(s, p)?.or(st.active_layer).ok_or_else(|| bad("no layer given and no active layer"))?;
     let l = st.doc.layer(id).ok_or(EngineError::NoLayer(id))?;
     if l.effects.items.is_empty() {
         return Err(bad(format!("layer {} has no effects", id.0)));
@@ -78,6 +74,7 @@ pub fn specs() -> Vec<CommandSpec> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use photocraft_doc::LayerId;
 
     /// A red layer with a drop shadow and a blue colour overlay, and the background (no effects).
     fn session() -> (Session, u64, u64) {
@@ -98,6 +95,14 @@ mod tests {
         (fx.enabled, fx.items.iter().map(|e| e.enabled()).collect())
     }
 
+    #[test]
+    fn named_nonactive_effects_layer_can_be_replayed() {
+        let (mut s, a, _) = session();
+        s.execute("layer.new.layer", json!({"name": "top"})).unwrap();
+        s.execute("layer.setEffectsVisible", json!({"layer": "a", "visible": false})).unwrap();
+        assert!(!state(&s, a).0);
+    }
+
     fn steps(s: &Session) -> usize {
         s.active().unwrap().history.past_len()
     }
diff --git a/crates/engine/src/cmd/layer_multi_cmds/selection.rs b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
index a0b5f76a77..943c41d886 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/selection.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
@@ -133,6 +133,10 @@ pub(super) fn same_named_targets(doc: &photocraft_doc::Document, name: &str, mov
 /// (omitting `layer`) so that the recorded step applies to whatever layer is targeted when
 /// replayed or exported to `.atn` (#7248).
 pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Option<&[LayerId]>) -> Value {
+    if id == "layer.new.frame" {
+        // An explicit layer is the frame content, even when it is the sole selection.
+        return p;
+    }
     if id == "layer.select" {
         return recorded_selection(s, p);
     }
diff --git a/crates/engine/src/cmd/type_mask_cmds.rs b/crates/engine/src/cmd/type_mask_cmds.rs
index 3a4b162a32..f09cc80122 100644
--- a/crates/engine/src/cmd/type_mask_cmds.rs
+++ b/crates/engine/src/cmd/type_mask_cmds.rs
@@ -8,7 +8,7 @@
 
 use photocraft_algo::selection::{self as sel, SelectionMode};
 use photocraft_doc::text::AntiAlias;
-use photocraft_doc::{Document, LayerContent, LayerId, TextLayer};
+use photocraft_doc::{Document, LayerContent, TextLayer};
 use photocraft_geom::Rect;
 use serde_json::{Value, json};
 
@@ -87,10 +87,7 @@ fn create_selection(s: &mut Session, p: &Value) -> Result<Value> {
         Some(v) => v.as_bool().ok_or_else(|| bad("removeLayer must be true or false"))?,
     };
     let doc = s.active().ok_or(EngineError::NoDocument)?.doc.clone();
-    let layer = match p.get("layer") {
-        None | Some(Value::Null) => None,
-        Some(v) => Some(LayerId(v.as_u64().ok_or_else(|| bad("layer must be a layer id"))?)),
-    };
+    let layer = crate::commands::explicit_layer(s, p)?;
     if remove && layer.is_none() {
         return Err(bad("removeLayer needs a layer"));
     }
@@ -144,7 +141,7 @@ pub fn specs() -> Vec<CommandSpec> {
         label: "Type Mask",
         menu: &[],
         shortcut: None,
-        params: r##"{"layer":id? (a type layer whose glyphs become the selection),"removeLayer":bool=false (delete that layer in the same step: the Type Mask tools' temporary text),"operation":"new|add|subtract|intersect"="new","antialias":"none|sharp|crisp|strong|smooth"?, …without "layer", type.create's keys: "text","x","y" or "box","orientation","font","size","align",…}"##,
+        params: r##"{"layer":id|name? (a type layer whose glyphs become the selection),"removeLayer":bool=false (delete that layer in the same step: the Type Mask tools' temporary text),"operation":"new|add|subtract|intersect"="new","antialias":"none|sharp|crisp|strong|smooth"?, …without "layer", type.create's keys: "text","x","y" or "box","orientation","font","size","align",…}"##,
         enabled: has_doc,
         journal: true,
         run: create_selection,
@@ -154,6 +151,7 @@ pub fn specs() -> Vec<CommandSpec> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use photocraft_doc::LayerId;
 
     fn session() -> Session {
         let mut s = Session::new();
@@ -165,6 +163,16 @@ mod tests {
         s.active().unwrap().doc.selection.as_ref().map(|m| m.content_bounds())
     }
 
+    #[test]
+    fn a_named_type_layer_can_make_a_selection_for_action_replay() {
+        let mut s = session();
+        let id = s.execute("type.create", json!({"text": "I", "x": 40, "y": 120, "size": 48})).unwrap()["layer"].as_u64().unwrap();
+        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({})).unwrap();
+        s.execute(CMD, json!({"layer": name})).unwrap();
+        assert!(bounds(&s).is_some());
+    }
+
     #[test]
     fn typed_text_selects_its_glyphs_without_a_layer() {
         let mut s = session();
diff --git a/crates/engine/src/cmd/type_styles_cmds.rs b/crates/engine/src/cmd/type_styles_cmds.rs
index 33c91f079b..9d6e68f091 100644
--- a/crates/engine/src/cmd/type_styles_cmds.rs
+++ b/crates/engine/src/cmd/type_styles_cmds.rs
@@ -430,6 +430,9 @@ fn new_style(s: &mut Session, p: &Value, paragraph: bool) -> Result<Value> {
     let (mut ca, mut pa) = parse_attrs(cmd, p.get("attrs").unwrap_or(&Value::Null))?;
     // With a type layer targeted, the style starts from the text's formatting (as Photoshop).
     let from_text = p.get("fromSelection").and_then(Value::as_bool).unwrap_or(true);
+    if from_text {
+        crate::commands::explicit_layer(s, p)?;
+    }
     if from_text && let Some((run, para, _, _)) = sample(s, p) {
         if paragraph {
             let base_c = st.resolve_char(None, None, FAMILY);
diff --git a/crates/engine/src/cmd/type_styles_cmds/tests.rs b/crates/engine/src/cmd/type_styles_cmds/tests.rs
index 6f6f735ff0..aba2f0fb5f 100644
--- a/crates/engine/src/cmd/type_styles_cmds/tests.rs
+++ b/crates/engine/src/cmd/type_styles_cmds/tests.rs
@@ -73,6 +73,15 @@ fn character_style_lifecycle() {
     assert_eq!(run_at(&layer(&s, id), 7).style_sheet, Some(cs as u32));
 }
 
+#[test]
+fn creating_a_style_rejects_an_unmatched_named_source_layer() {
+    let (mut s, _) = session("Hello");
+    for id in ["type.characterStyle.new", "type.paragraphStyle.new"] {
+        let error = s.execute(id, json!({"name": "From missing", "layer": "Missing", "fromSelection": true})).unwrap_err();
+        assert!(error.to_string().contains("no layer named"), "{error}");
+    }
+}
+
 #[test]
 fn new_style_from_selection_and_redefine() {
     let (mut s, id) = session("Title");
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index b7d724a09b..fc5fd359b0 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -982,7 +982,6 @@ impl Session {
         let params = crate::actions_record::portable(id, params, before);
         match crate::actions_record::fold_keystroke(self, id, &params, self.typed_layer) {
             crate::actions_record::Keystroke::Folded => {}
-            crate::actions_record::Keystroke::Step(step) => self.journal.push((id.to_string(), step)),
             crate::actions_record::Keystroke::None => {
                 if !crate::brush_cmds::coalesce_journal(self, id, &params) {
                     self.journal.push((id.to_string(), params));
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index a7bb6a5f80..d0ab53b25b 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped; other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes fold into a whole-text `type.create`/`type.edit` step within the same document and layer. Ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped; other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |

From dc28eb5083e14bdcce4207e9519ceda83f94e85a Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 00:25:43 -0600
Subject: [PATCH 044/109] Stream batch directory scans and report cancellations
 accurately

---
 apps/photocraft-cli/src/batch.rs             | 18 +++++++-------
 crates/engine/src/cmd/file_cmds/batch_run.rs | 12 +++++++---
 crates/engine/src/cmd/file_cmds/paths.rs     | 16 ++++++-------
 crates/engine/src/cmd/file_cmds/tests.rs     | 10 ++++++++
 crates/engine/src/jobs.rs                    |  9 ++++---
 crates/engine/src/jobs/tests.rs              | 23 ++++++++++++++++++
 crates/ui-egui/src/jobs_ui.rs                |  7 ++++++
 crates/ui-egui/src/jobs_ui/tests.rs          | 25 ++++++++++++++++++++
 8 files changed, 97 insertions(+), 23 deletions(-)

diff --git a/apps/photocraft-cli/src/batch.rs b/apps/photocraft-cli/src/batch.rs
index 15abd8848c..354c06b58c 100644
--- a/apps/photocraft-cli/src/batch.rs
+++ b/apps/photocraft-cli/src/batch.rs
@@ -64,15 +64,15 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
             .filter(|input| is_input(Path::new(&input.path)))
             .collect()
     } else {
-        std::fs::read_dir(in_dir)
-            .map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?
-            .map(|entry| entry.map(|entry| entry.path()))
-            .collect::<std::io::Result<Vec<_>>>()
-            .map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?
-            .into_iter()
-            .filter(|path| is_input(path))
-            .map(|path| photocraft_engine::file_cmds::BatchInput { path: path.to_string_lossy().into_owned(), rel_dir: String::new() })
-            .collect()
+        let mut images = Vec::new();
+        let entries = std::fs::read_dir(in_dir).map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?;
+        for entry in entries {
+            let path = entry.map_err(|source| CliError::ReadDir { path: in_dir.to_path_buf(), source })?.path();
+            if is_input(&path) {
+                images.push(photocraft_engine::file_cmds::BatchInput { path: path.to_string_lossy().into_owned(), rel_dir: String::new() });
+            }
+        }
+        images
     };
     inputs.sort_by(|a, b| a.path.cmp(&b.path));
     let (mut ok, mut failed) = (0, 0);
diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 93e8da6d66..66c54b0dea 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -74,9 +74,15 @@ pub fn list_images_tree(dir: &str, skip: &str, cmd: &str) -> Result<Vec<BatchInp
             continue;
         }
         let rd = std::fs::read_dir(&folder).map_err(|e| EngineError::Other(format!("{shown}: {e}")))?;
-        let entries = rd.collect::<std::io::Result<Vec<_>>>().map_err(|e| EngineError::Other(format!("{shown}: {e}")))?;
-        let mut subs: Vec<(String, PathBuf)> =
-            entries.into_iter().map(|e| e.path()).filter(|p| p.is_dir()).filter_map(|p| Some((p.file_name()?.to_string_lossy().into_owned(), p))).collect();
+        let mut subs: Vec<(String, PathBuf)> = Vec::new();
+        for entry in rd {
+            let path = entry.map_err(|e| EngineError::Other(format!("{shown}: {e}")))?.path();
+            if path.is_dir()
+                && let Some(name) = path.file_name()
+            {
+                subs.push((name.to_string_lossy().into_owned(), path.clone()));
+            }
+        }
         subs.sort();
         // Pushed in reverse so the stack pops them in name order.
         for (name, sub) in subs.into_iter().rev() {
diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index 63455286ec..68f1c513d6 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -40,13 +40,13 @@ pub(crate) fn write_file(path: &str, _bytes: &[u8]) -> Result<()> {
 #[cfg(not(target_arch = "wasm32"))]
 pub fn list_images(dir: &str) -> Result<Vec<String>> {
     let rd = std::fs::read_dir(dir).map_err(|e| EngineError::Other(format!("{dir}: {e}")))?;
-    let entries = rd.collect::<std::io::Result<Vec<_>>>().map_err(|e| EngineError::Other(format!("{dir}: {e}")))?;
-    let mut out: Vec<String> = entries
-        .into_iter()
-        .map(|e| e.path())
-        .filter(|p| p.is_file() && openable_name(&p.to_string_lossy()))
-        .map(|p| p.to_string_lossy().into_owned())
-        .collect();
+    let mut out = Vec::new();
+    for entry in rd {
+        let path = entry.map_err(|e| EngineError::Other(format!("{dir}: {e}")))?.path();
+        if path.is_file() && openable_name(&path.to_string_lossy()) {
+            out.push(path.to_string_lossy().into_owned());
+        }
+    }
     out.sort();
     Ok(out)
 }
@@ -224,7 +224,7 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
                 #[cfg(any(target_os = "windows", target_os = "macos"))]
                 {
                     match (a.to_str(), b.to_str()) {
-                        (Some(a), Some(b)) => a.eq_ignore_ascii_case(b),
+                        (Some(a), Some(b)) => a.to_lowercase() == b.to_lowercase(),
                         _ => a == b,
                     }
                 }
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index ef9758fa53..d1159aaabc 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -103,6 +103,13 @@ fn linux_distinct_case_destinations_are_not_the_same_file() {
     assert!(!same_destination(join(&dir, "Image.png"), join(&dir, "image.png")));
 }
 
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+#[test]
+fn unicode_case_variants_cannot_name_a_batch_output_and_its_error_log() {
+    let dir = tmp("batch-unicode-case-destinations");
+    assert!(same_destination(join(&dir, "Ä.png"), join(&dir, "ä.png")));
+}
+
 #[test]
 fn batch_open_source_edits_each_live_document_and_restores_the_active_one() {
     let dir = tmp("batch-open-documents");
@@ -179,6 +186,9 @@ fn recursive_batch_reports_an_unreadable_subfolder() {
     std::fs::set_permissions(&sub, std::fs::Permissions::from_mode(0o700)).unwrap();
     if inaccessible {
         assert!(result.is_err(), "an inaccessible input folder must not be omitted");
+    } else {
+        eprintln!("permission regression skipped: this user can read a mode-000 folder");
+        assert!(result.is_ok(), "a privileged reader should still process the folder");
     }
 }
 
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index 3c2cb9e3b9..b8d5e68ac6 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -701,6 +701,9 @@ impl Session {
         // Earlier batch outputs are already on disk. Let the worker stop after its current
         // input and return the completed and skipped lists.
         if self.jobs.running[i].command == "file.automate.batch" {
+            if self.jobs.running[i].ctx.cancelled() {
+                return false;
+            }
             self.jobs.running[i].ctx.cancel();
             return true;
         }
@@ -1124,9 +1127,9 @@ pub fn specs() -> Vec<crate::commands::CommandSpec> {
             enabled: |_| Ok(()),
             run: |s, p| match p.get("job") {
                 None | Some(Value::Null) => {
-                    let n = s.jobs.running.len();
-                    s.cancel_all_jobs();
-                    Ok(json!({"cancelled": n.saturating_sub(s.jobs.running.len())}))
+                    let ids: Vec<JobId> = s.jobs.running.iter().map(|job| job.id).collect();
+                    let accepted = ids.into_iter().filter(|id| s.cancel_job(*id)).count();
+                    Ok(json!({"cancelled": accepted}))
                 }
                 Some(v) => {
                     let id = v.as_u64().ok_or_else(|| EngineError::BadParams { cmd: "jobs.cancel".into(), msg: "`job` must be a job id".into() })?;
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index 19502cae35..cbb8b74059 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -569,6 +569,29 @@ fn cancelled_batch_job_returns_its_partial_result() {
     assert_eq!(result["cancelled"], true);
 }
 
+#[test]
+fn cancel_all_counts_an_accepted_batch_cancellation() {
+    let mut s = Session::new();
+    let id = job(s
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            |ctx| {
+                while !ctx.cancelled() {
+                    std::thread::sleep(Duration::from_millis(2));
+                }
+                Ok(json!({"files": [], "cancelled": true}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap());
+    assert_eq!(s.execute("jobs.cancel", json!({})).unwrap()["cancelled"], 1);
+    assert_eq!(s.execute("jobs.cancel", json!({})).unwrap()["cancelled"], 0, "a repeated request is not a new cancellation");
+    assert!(matches!(wait_event(&mut s, id).outcome, JobOutcome::Done(_)));
+}
+
 /// Ask When Opening: a file whose profile doesn't match is decoded but not added; the shell takes
 /// it once the prompt is answered. Without Ask it opens as usual.
 #[test]
diff --git a/crates/ui-egui/src/jobs_ui.rs b/crates/ui-egui/src/jobs_ui.rs
index 00fce3da53..83bd7e2753 100644
--- a/crates/ui-egui/src/jobs_ui.rs
+++ b/crates/ui-egui/src/jobs_ui.rs
@@ -448,9 +448,12 @@ pub fn cancel(app: &mut PhotocraftApp, id: JobId) -> bool {
 }
 
 fn on_event(app: &mut PhotocraftApp, ctx: &egui::Context, e: JobEvent) {
+    let cancelled_batch =
+        e.command == "file.automate.batch" && matches!(&e.outcome, JobOutcome::Done(result) if result.get("cancelled").and_then(Value::as_bool) == Some(true));
     // Preferences ▸ General ▸ Beep When Done (off by default): a finished operation beeps, like
     // Photoshop's cue. Cancelling is the user's own action and stays silent.
     if matches!(e.outcome, JobOutcome::Done(_))
+        && !cancelled_batch
         && app.session.prefs().general.beep_when_done
         && let Some(beep) = app.services.beep
     {
@@ -526,6 +529,10 @@ fn on_event(app: &mut PhotocraftApp, ctx: &egui::Context, e: JobEvent) {
             app.sync_views();
             crate::file_ui::print_status(app, result);
         }
+        JobOutcome::Done(_) if cancelled_batch => {
+            app.ui.status = crate::i18n::fmt(tl!("Cancelled {label}"), &[("label", &e.label)]);
+            app.ui.status_error = false;
+        }
         JobOutcome::Done(_) => {
             app.sync_views();
             app.ui.status = e.label;
diff --git a/crates/ui-egui/src/jobs_ui/tests.rs b/crates/ui-egui/src/jobs_ui/tests.rs
index 4377074ed5..12f6b0901d 100644
--- a/crates/ui-egui/src/jobs_ui/tests.rs
+++ b/crates/ui-egui/src/jobs_ui/tests.rs
@@ -748,6 +748,31 @@ fn a_finished_job_beeps_when_the_preference_is_on() {
     assert_eq!(BEEPS.load(Ordering::Relaxed), 1, "one beep for the finished job");
 }
 
+#[test]
+fn cancelled_batch_with_partial_results_reports_cancellation_without_beeping() {
+    static BEEPS: AtomicUsize = AtomicUsize::new(0);
+    fn count_beep() {
+        BEEPS.fetch_add(1, Ordering::Relaxed);
+    }
+    BEEPS.store(0, Ordering::Relaxed);
+    let mut h = app_harness_with(crate::Services { beep: Some(count_beep), ..Default::default() });
+    h.state_mut().run("prefs.set", json!({"path": "general.beepWhenDone", "value": true})).unwrap();
+    let ctx = h.ctx.clone();
+    crate::jobs_ui::on_event(
+        h.state_mut(),
+        &ctx,
+        photocraft_engine::jobs::JobEvent {
+            id: JobId(9999),
+            command: "file.automate.batch".into(),
+            label: "Batch".into(),
+            document: None,
+            outcome: photocraft_engine::jobs::JobOutcome::Done(json!({"files": ["done.png"], "cancelled": true})),
+        },
+    );
+    assert!(h.state().ui.status.contains("Cancelled"), "{}", h.state().ui.status);
+    assert_eq!(BEEPS.load(Ordering::Relaxed), 0);
+}
+
 #[test]
 fn printing_keeps_drawing_and_reports_only_the_final_spooler_result() {
     for success in [true, false] {

From b82a354718024c4d81e70354bde80d8e0c7174d5 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 00:43:44 -0600
Subject: [PATCH 045/109] Preserve explicit action sources and replay named
 spelling edits

---
 crates/engine/src/actions_record.rs           |  7 ++-
 crates/engine/src/actions_record/tests.rs     | 47 +++++++++++++++++++
 crates/engine/src/cmd/fx_visibility_cmds.rs   | 11 ++++-
 .../src/cmd/layer_multi_cmds/selection.rs     |  4 +-
 crates/engine/src/cmd/type_spell_cmds.rs      | 21 ++++++++-
 docs/control-protocol.md                      |  2 +-
 6 files changed, 85 insertions(+), 7 deletions(-)

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
index f55efee176..6745f40321 100644
--- a/crates/engine/src/actions_record.rs
+++ b/crates/engine/src/actions_record.rs
@@ -40,13 +40,18 @@ impl Before {
     }
 }
 
+/// Commands whose explicit `layer` names source content rather than a default target.
+pub(crate) fn needs_source_layer(id: &str) -> bool {
+    matches!(id, "layer.new.frame" | "select.loadSelection" | "type.createSelection")
+}
+
 /// `params` with its `layer` id made portable (see the module doc).
 pub(crate) fn portable(id: &str, mut params: Value, before: &Before) -> Value {
     let Some(doc) = before.doc.as_deref() else { return params };
     let Some(target) = params.get("layer").and_then(Value::as_u64).map(LayerId) else { return params };
     let Some(obj) = params.as_object_mut() else { return params };
     let only_selected = before.selected.len() <= 1;
-    if !matches!(id, "layer.select" | "layer.new.frame") && before.active_layer == Some(target) && only_selected {
+    if id != "layer.select" && !needs_source_layer(id) && before.active_layer == Some(target) && only_selected {
         obj.remove("layer");
         return params;
     }
diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index b769554120..57659b4db5 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -105,6 +105,53 @@ fn frame_action_keeps_the_layer_it_wraps() {
     s.execute("actions.stop", json!({})).unwrap();
     let steps = s.execute("actions.get", json!({"action": "Frame picture"})).unwrap()["steps"].clone();
     assert_eq!(steps[0][1]["layer"], "Picture", "the frame must wrap the recorded source layer");
+    s.execute("file.new", json!({"width": 32, "height": 32, "background": "white"})).unwrap();
+    new_layer(&mut s, "Spare");
+    let target = new_layer(&mut s, "Picture");
+    assert_ne!(target, picture, "the replay target has a different document-local id");
+    let played = s.execute("actions.play", json!({"action": "Frame picture"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    assert!(
+        s.active().unwrap().doc.walk().iter().any(
+            |(_, _, layer)| matches!(&layer.content, photocraft_doc::LayerContent::Group(group) if group.children.iter().any(|child| child.id.0 == target))
+        ),
+        "the replayed frame wraps Picture"
+    );
+}
+
+#[test]
+fn selection_actions_keep_the_active_layer_as_their_source() {
+    let mut s = session();
+    let raster = new_layer(&mut s, "Pixels");
+    s.execute("actions.record", json!({"name": "Load pixels"})).unwrap();
+    s.execute("select.loadSelection", json!({"channel": "transparency", "layer": raster})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Load pixels"})).unwrap()["steps"].clone();
+    assert_eq!(steps[0][1]["layer"], "Pixels", "missing layer loads merged pixels instead");
+    s.execute("file.new", json!({"width": 32, "height": 32, "background": "white"})).unwrap();
+    new_layer(&mut s, "Pixels");
+    let played = s.execute("actions.play", json!({"action": "Load pixels"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    assert_eq!(
+        s.active().unwrap().doc.selection.as_ref().map(|mask| mask.content_bounds()).unwrap_or(photocraft_geom::Rect::EMPTY),
+        photocraft_geom::Rect::EMPTY,
+        "the empty source layer must not load the opaque merged document"
+    );
+
+    let type_id = s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let type_name = s.active().unwrap().doc.layer(LayerId(type_id)).unwrap().name.clone();
+    s.execute("actions.record", json!({"name": "Mask text"})).unwrap();
+    s.execute("type.createSelection", json!({"layer": type_id, "removeLayer": true})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Mask text"})).unwrap()["steps"].clone();
+    assert_eq!(steps[0][1]["layer"], type_name, "without the source, replay cannot remove that type layer");
+    s.execute("file.new", json!({"width": 32, "height": 32, "background": "white"})).unwrap();
+    new_layer(&mut s, "Spare");
+    let replay_type = s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    assert_ne!(replay_type, type_id);
+    let played = s.execute("actions.play", json!({"action": "Mask text"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    assert!(s.active().unwrap().doc.layer(LayerId(replay_type)).is_none(), "replay removed the named source type layer");
 }
 
 #[test]
diff --git a/crates/engine/src/cmd/fx_visibility_cmds.rs b/crates/engine/src/cmd/fx_visibility_cmds.rs
index ba121f7f3c..dadb8f888b 100644
--- a/crates/engine/src/cmd/fx_visibility_cmds.rs
+++ b/crates/engine/src/cmd/fx_visibility_cmds.rs
@@ -99,8 +99,17 @@ mod tests {
     fn named_nonactive_effects_layer_can_be_replayed() {
         let (mut s, a, _) = session();
         s.execute("layer.new.layer", json!({"name": "top"})).unwrap();
-        s.execute("layer.setEffectsVisible", json!({"layer": "a", "visible": false})).unwrap();
+        let replay = s.active().unwrap().doc.as_ref().clone();
+        s.execute("actions.record", json!({"name": "Hide effects"})).unwrap();
+        s.execute("layer.setEffectsVisible", json!({"layer": a, "visible": false})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
         assert!(!state(&s, a).0);
+        let steps = s.execute("actions.get", json!({"action": "Hide effects"})).unwrap()["steps"].clone();
+        assert_eq!(steps[0][1]["layer"], "a");
+        s.add_document(replay, None);
+        let played = s.execute("actions.play", json!({"action": "Hide effects"})).unwrap();
+        assert!(played.get("failed").is_none(), "{played}");
+        assert!(!state(&s, a).0, "the recorded name targeted the nonactive layer on replay");
     }
 
     fn steps(s: &Session) -> usize {
diff --git a/crates/engine/src/cmd/layer_multi_cmds/selection.rs b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
index 943c41d886..1ade1a4151 100644
--- a/crates/engine/src/cmd/layer_multi_cmds/selection.rs
+++ b/crates/engine/src/cmd/layer_multi_cmds/selection.rs
@@ -133,8 +133,8 @@ pub(super) fn same_named_targets(doc: &photocraft_doc::Document, name: &str, mov
 /// (omitting `layer`) so that the recorded step applies to whatever layer is targeted when
 /// replayed or exported to `.atn` (#7248).
 pub(crate) fn recorded_step(s: &Session, id: &str, p: Value, pre_selected: Option<&[LayerId]>) -> Value {
-    if id == "layer.new.frame" {
-        // An explicit layer is the frame content, even when it is the sole selection.
+    if crate::actions_record::needs_source_layer(id) {
+        // An explicit layer supplies content, even when it is the sole selection.
         return p;
     }
     if id == "layer.select" {
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index d42500c722..c7fef5ae26 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -117,7 +117,7 @@ fn list(s: &Session, p: &Value) -> Result<Value> {
 /// Replaces one occurrence (verified to still be `word` when given).
 fn change(s: &mut Session, p: &Value) -> Result<Value> {
     let cmd = "edit.checkSpelling";
-    let id = LayerId(p.get("layer").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `layer`"))?);
+    let id = crate::commands::explicit_layer(s, p)?.ok_or_else(|| bad(cmd, "`change` needs `layer`"))?;
     let start = p.get("start").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `start`"))? as usize;
     let end = p.get("end").and_then(Value::as_u64).ok_or_else(|| bad(cmd, "`change` needs `end`"))? as usize;
     let to = p.get("replace").and_then(Value::as_str).ok_or_else(|| bad(cmd, "`change` needs `replace`"))?.to_string();
@@ -270,7 +270,7 @@ pub fn specs() -> Vec<CommandSpec> {
             label: "Check Spelling…",
             menu: &["Edit"],
             shortcut: None,
-            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer","start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"}"#,
+            params: r#"{"action":"list|change|changeAll|addToDictionary|removeFromDictionary|suggest"="list","allLayers":bool=true,"layer":id|name? (check one layer),"ignore":[word]? (Ignore All for this check),"suggestions":n=5; change: "layer","start","end" (chars),"word"? (verified),"replace"; changeAll: "word","replace"; addToDictionary/removeFromDictionary/suggest: "word"} → list: {"misspellings":[{"layer","start","end","word","suggestions"}],"count"}"#,
             enabled: has_type,
             journal: true,
             run: check_spelling,
@@ -314,6 +314,23 @@ mod tests {
         text(&s.active().unwrap().doc, LayerId(id)).unwrap().to_string()
     }
 
+    #[test]
+    fn a_recorded_spelling_change_replays_on_a_named_nonactive_layer() {
+        let (mut s, id) = session("Teh");
+        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+        let replay = s.active().unwrap().doc.as_ref().clone();
+        s.execute("actions.record", json!({"name": "Fix spelling"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        let steps = s.execute("actions.get", json!({"action": "Fix spelling"})).unwrap()["steps"].clone();
+        assert_eq!(steps[0][1]["layer"], name);
+        s.add_document(replay, None);
+        let played = s.execute("actions.play", json!({"action": "Fix spelling"})).unwrap();
+        assert!(played.get("failed").is_none(), "{played}");
+        assert_eq!(text_of(&s, id), "The");
+    }
+
     #[test]
     fn all_locked_layer_rejects_insert_text_and_spelling_change_without_history() {
         // #4188: Lock All stopped type.edit (#3132) but not these two text edits.
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index d0ab53b25b..7cb6f7fc32 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped; other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped unless it supplies source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`); other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |

From ffaeedefa839720e69c9fbd2e1c6c6b4de96d685 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 00:52:59 -0600
Subject: [PATCH 046/109] Guard late Batch cancellation and report metadata
 failures

---
 crates/engine/src/cmd/file_cmds/paths.rs | 10 ++++++--
 crates/engine/src/cmd/file_cmds/tests.rs | 20 +++++++++++++++
 crates/engine/src/jobs.rs                | 32 +++++++++++++++++-------
 crates/engine/src/jobs/tests.rs          | 18 +++++++++++++
 4 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index 68f1c513d6..d2124957bc 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -43,8 +43,14 @@ pub fn list_images(dir: &str) -> Result<Vec<String>> {
     let mut out = Vec::new();
     for entry in rd {
         let path = entry.map_err(|e| EngineError::Other(format!("{dir}: {e}")))?.path();
-        if path.is_file() && openable_name(&path.to_string_lossy()) {
-            out.push(path.to_string_lossy().into_owned());
+        if !openable_name(&path.to_string_lossy()) {
+            continue;
+        }
+        match std::fs::metadata(&path) {
+            Ok(metadata) if metadata.is_file() => out.push(path.to_string_lossy().into_owned()),
+            Ok(_) => {}
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} // broken link or entry removed during traversal
+            Err(error) => return Err(EngineError::Other(format!("{}: {error}", path.display()))),
         }
     }
     out.sort();
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index d1159aaabc..52af9722c8 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -192,6 +192,26 @@ fn recursive_batch_reports_an_unreadable_subfolder() {
     }
 }
 
+#[cfg(unix)]
+#[test]
+fn folder_listing_reports_metadata_denial_and_skips_broken_links() {
+    use std::os::unix::fs::{PermissionsExt, symlink};
+    let dir = tmp("batch-list-metadata-denial");
+    let image = png(&dir, "image.png", 8, 6, "#ff0000");
+    symlink(join(&dir, "gone.png"), join(&dir, "broken.png")).unwrap();
+    assert_eq!(list_images(&dir).unwrap(), std::slice::from_ref(&image), "broken links are not inputs");
+    std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o400)).unwrap();
+    let denied = std::fs::metadata(&image).is_err();
+    let result = list_images(&dir);
+    std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap();
+    if denied {
+        assert!(result.is_err(), "metadata denial must not turn a folder of images into an empty batch");
+    } else {
+        eprintln!("metadata denial regression skipped: this user can search a mode-0400 folder");
+        assert_eq!(result.unwrap(), [image]);
+    }
+}
+
 #[test]
 fn close_all_and_close_others() {
     let mut s = session(8, 8, 8);
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index b8d5e68ac6..b62c6b6338 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -19,7 +19,7 @@
 //!   message naming the job (queries and document-independent commands still run).
 
 use std::any::Any;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicU8, AtomicU32, Ordering};
 use std::sync::{Arc, Mutex, PoisonError, Weak};
 
 use photocraft_doc::{DocId, Document, LayerId};
@@ -84,13 +84,16 @@ pub struct JobCtx {
 
 #[derive(Default)]
 struct Shared {
-    cancel: AtomicBool,
+    state: AtomicU8,
     /// `f32` bits of the progress fraction. Non-negative floats order like their bits, so
     /// `fetch_max` keeps progress monotonic even with several reporting threads.
     progress: AtomicU32,
     message: Mutex<String>,
 }
 
+const CANCEL_REQUESTED: u8 = 1;
+const WORK_FINISHED: u8 = 2;
+
 impl std::fmt::Debug for JobCtx {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("JobCtx").field("progress", &self.fraction()).field("cancelled", &self.cancelled()).finish()
@@ -118,12 +121,26 @@ impl JobCtx {
 
     /// Has the job been cancelled? Long loops check this and stop early.
     pub fn cancelled(&self) -> bool {
-        self.shared.cancel.load(Ordering::Relaxed)
+        self.shared.state.load(Ordering::Acquire) & CANCEL_REQUESTED != 0
     }
 
     /// Ask the job to stop (idempotent).
     pub fn cancel(&self) {
-        self.shared.cancel.store(true, Ordering::Relaxed);
+        self.shared.state.fetch_or(CANCEL_REQUESTED, Ordering::AcqRel);
+    }
+
+    /// Accept a cancellation only while the worker has not finished its result. One atomic state
+    /// orders a late cancel against completion, including the interval before the UI polls.
+    fn cancel_if_running(&self) -> bool {
+        self.shared
+            .state
+            .try_update(Ordering::AcqRel, Ordering::Acquire, |state| (state & (CANCEL_REQUESTED | WORK_FINISHED) == 0).then_some(state | CANCEL_REQUESTED))
+            .is_ok()
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    fn finish_work(&self) {
+        self.shared.state.fetch_or(WORK_FINISHED, Ordering::Release);
     }
 
     /// `Err(Cancelled)` once cancelled, for `?` between stages.
@@ -406,6 +423,7 @@ pub fn run<T: Send + 'static>(
             let _document = crate::doc_path::scope(document.as_deref());
             let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| work(&wctx).map(|t| Box::new(t) as Payload)))
                 .unwrap_or_else(|_| Err(EngineError::Other(format!("`{label_w}` failed with an internal error (logged); the document is unchanged"))));
+            wctx.finish_work();
             // The receiver is gone when the job was cancelled: nothing to report.
             let _ = tx.send(r);
         });
@@ -701,11 +719,7 @@ impl Session {
         // Earlier batch outputs are already on disk. Let the worker stop after its current
         // input and return the completed and skipped lists.
         if self.jobs.running[i].command == "file.automate.batch" {
-            if self.jobs.running[i].ctx.cancelled() {
-                return false;
-            }
-            self.jobs.running[i].ctx.cancel();
-            return true;
+            return self.jobs.running[i].ctx.cancel_if_running();
         }
         // A print worker can already have handed the job to the OS. Discarding its result
         // would falsely report cancellation; removal belongs to the system print queue.
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index cbb8b74059..ba53e0f6b2 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -592,6 +592,24 @@ fn cancel_all_counts_an_accepted_batch_cancellation() {
     assert!(matches!(wait_event(&mut s, id).outcome, JobOutcome::Done(_)));
 }
 
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn a_finished_batch_worker_rejects_late_cancellation() {
+    let mut s = Session::new();
+    let id = job(s
+        .start_job("file.automate.batch", json!({}), "Batch", false, |_| Ok(json!({"files": ["done.png"], "cancelled": false})), |_, result| Ok(result))
+        .unwrap());
+    let started = Instant::now();
+    while !s.jobs.running.iter().any(|running| running.id == id && running.handle.as_ref().is_some_and(|handle| handle.is_finished())) {
+        assert!(started.elapsed() < Duration::from_secs(10), "batch worker did not finish");
+        std::thread::sleep(Duration::from_millis(2));
+    }
+    assert!(!s.cancel_job(id), "a result already sent cannot be cancelled");
+    let JobOutcome::Done(result) = wait_event(&mut s, id).outcome else { panic!("completed batch result was lost") };
+    assert_eq!(result["files"], json!(["done.png"]));
+    assert_eq!(result["cancelled"], false);
+}
+
 /// Ask When Opening: a file whose profile doesn't match is decoded but not added; the shell takes
 /// it once the prompt is answered. Without Ask it opens as usual.
 #[test]

From 771b33d51e862d4d01b67cc73f44c657186f923f Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 01:00:31 -0600
Subject: [PATCH 047/109] Respect destination case behavior and report repeated
 Batch cancel

---
 crates/engine/src/cmd/file_cmds/paths.rs | 20 +++++++++++++++++++-
 crates/engine/src/cmd/file_cmds/tests.rs |  7 +++++--
 crates/engine/src/jobs.rs                |  2 ++
 crates/engine/src/jobs/tests.rs          |  1 +
 4 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index d2124957bc..e0cf4433cb 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -216,6 +216,24 @@ pub fn destination_identity(path: &std::path::Path) -> Option<std::path::PathBuf
     Some(resolved)
 }
 
+/// Probe the actual destination directory. macOS volumes and Windows directories may use either
+/// case behavior; the OS name alone cannot tell whether two future names will alias.
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+fn case_sensitive_destination(path: &std::path::Path) -> Option<bool> {
+    let parent = path.parent()?;
+    if !std::fs::metadata(parent).ok()?.is_dir() {
+        return None;
+    }
+    let probe = tempfile::Builder::new().prefix(".PhotoCraftCaseProbe-").tempfile_in(parent).ok()?;
+    let name = probe.path().file_name()?.to_str()?;
+    let alternate = parent.join(name.replacen("PhotoCraft", "photocraft", 1));
+    match std::fs::metadata(&alternate) {
+        Ok(_) => Some(!same_file(probe.path(), &alternate)),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Some(true),
+        Err(_) => None,
+    }
+}
+
 /// Whether two paths would name the same destination even before the file exists. This is used
 /// when a batch error log must not be allowed to replace a result that will be written later.
 pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path::Path>) -> bool {
@@ -230,7 +248,7 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
                 #[cfg(any(target_os = "windows", target_os = "macos"))]
                 {
                     match (a.to_str(), b.to_str()) {
-                        (Some(a), Some(b)) => a.to_lowercase() == b.to_lowercase(),
+                        (Some(a_text), Some(b_text)) if a_text.to_lowercase() == b_text.to_lowercase() => !case_sensitive_destination(&a).unwrap_or(false),
                         _ => a == b,
                     }
                 }
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 52af9722c8..8de4564672 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -105,9 +105,12 @@ fn linux_distinct_case_destinations_are_not_the_same_file() {
 
 #[cfg(any(target_os = "macos", target_os = "windows"))]
 #[test]
-fn unicode_case_variants_cannot_name_a_batch_output_and_its_error_log() {
+fn unicode_case_variants_follow_destination_volume() {
     let dir = tmp("batch-unicode-case-destinations");
-    assert!(same_destination(join(&dir, "Ä.png"), join(&dir, "ä.png")));
+    let existing = join(&dir, "Ä-probe");
+    std::fs::write(&existing, b"probe").unwrap();
+    let volume_aliases_case = same_file(&existing, join(&dir, "ä-probe"));
+    assert_eq!(same_destination(join(&dir, "Ä.png"), join(&dir, "ä.png")), volume_aliases_case);
 }
 
 #[test]
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index b62c6b6338..5111fe1635 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -1149,6 +1149,8 @@ pub fn specs() -> Vec<crate::commands::CommandSpec> {
                     let id = v.as_u64().ok_or_else(|| EngineError::BadParams { cmd: "jobs.cancel".into(), msg: "`job` must be a job id".into() })?;
                     if s.cancel_job(JobId(id)) {
                         Ok(json!({"cancelled": 1}))
+                    } else if s.job(JobId(id)).is_some_and(|job| job.command == "file.automate.batch") {
+                        Ok(json!({"cancelled": 0}))
                     } else if s.job(JobId(id)).is_some() {
                         Err(EngineError::Other("printing cannot be cancelled here; use the system print queue".into()))
                     } else {
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index ba53e0f6b2..da07db5002 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -589,6 +589,7 @@ fn cancel_all_counts_an_accepted_batch_cancellation() {
         .unwrap());
     assert_eq!(s.execute("jobs.cancel", json!({})).unwrap()["cancelled"], 1);
     assert_eq!(s.execute("jobs.cancel", json!({})).unwrap()["cancelled"], 0, "a repeated request is not a new cancellation");
+    assert_eq!(s.execute("jobs.cancel", json!({"job": id.0})).unwrap()["cancelled"], 0, "a repeated batch request is not a print error");
     assert!(matches!(wait_event(&mut s, id).outcome, JobOutcome::Done(_)));
 }
 

From 061da0cf7f1128b7a1e27b902d3cc99192498ba0 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 01:08:50 -0600
Subject: [PATCH 048/109] Resolve named action layers in admission and command
 handlers

---
 crates/engine/src/actions_record/tests.rs   | 34 +++++++++++++++++++++
 crates/engine/src/cmd/smart_cmds/placing.rs |  4 +--
 crates/engine/src/cmd/type_spell_cmds.rs    | 23 +++++++++-----
 crates/engine/src/session/execute.rs        |  2 +-
 4 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index 57659b4db5..18c53b445a 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -151,9 +151,43 @@ fn selection_actions_keep_the_active_layer_as_their_source() {
     assert_ne!(replay_type, type_id);
     let played = s.execute("actions.play", json!({"action": "Mask text"})).unwrap();
     assert!(played.get("failed").is_none(), "{played}");
+    assert!(s.active().unwrap().doc.selection.as_ref().is_some_and(|mask| !mask.content_bounds().is_empty()), "replay selects the glyphs");
     assert!(s.active().unwrap().doc.layer(LayerId(replay_type)).is_none(), "replay removed the named source type layer");
 }
 
+#[test]
+fn named_nonactive_smart_layer_passes_admission_and_converts_to_layers() {
+    let mut s = session();
+    s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap();
+    let smart = s.execute("layer.smartObjects.convertToSmartObject", json!({})).unwrap()["layer"].as_u64().unwrap();
+    let name = s.active().unwrap().doc.layer(LayerId(smart)).unwrap().name.clone();
+    let top = new_layer(&mut s, "Top");
+    s.execute("layer.smartObjects.convertToLayers", json!({"layer": name})).unwrap();
+    assert!(s.active().unwrap().doc.layer(LayerId(smart)).is_none());
+    assert!(s.active().unwrap().doc.layer(LayerId(top)).is_some());
+}
+
+#[test]
+fn named_nonactive_layer_is_the_one_converted_to_smart() {
+    let mut s = session();
+    let target = s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let name = s.active().unwrap().doc.layer(LayerId(target)).unwrap().name.clone();
+    new_layer(&mut s, "Top");
+    s.execute("actions.record", json!({"name": "Convert source"})).unwrap();
+    s.execute("layer.smartObjects.convertToSmartObject", json!({"layer": target})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = s.execute("actions.get", json!({"action": "Convert source"})).unwrap()["steps"].clone();
+    assert_eq!(steps[0][1]["layer"], name, "the journal names the explicit source");
+
+    s.execute("file.new", json!({"width": 32, "height": 32, "background": "white"})).unwrap();
+    let replay_target = s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap()["layer"].as_u64().unwrap();
+    let top = new_layer(&mut s, "Top");
+    let played = s.execute("actions.play", json!({"action": "Convert source"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    assert!(s.active().unwrap().doc.layer(LayerId(replay_target)).is_none(), "replay removes the named source");
+    assert!(s.active().unwrap().doc.layer(LayerId(top)).is_some(), "replay keeps the selected top layer");
+}
+
 #[test]
 fn merged_named_layer_keeps_its_id_as_a_selection_source() {
     let mut s = session();
diff --git a/crates/engine/src/cmd/smart_cmds/placing.rs b/crates/engine/src/cmd/smart_cmds/placing.rs
index d2e4420aca..847ad700db 100644
--- a/crates/engine/src/cmd/smart_cmds/placing.rs
+++ b/crates/engine/src/cmd/smart_cmds/placing.rs
@@ -197,8 +197,8 @@ pub fn layers_to_smart(doc: &Document, name: &str, layers: Vec<Layer>) -> Result
 }
 
 pub(super) fn convert(s: &mut Session, p: &Value) -> Result<Value> {
-    let ids = match p.get("layer").and_then(Value::as_u64) {
-        Some(id) => vec![LayerId(id)],
+    let ids = match crate::commands::explicit_layer(s, p)? {
+        Some(id) => vec![id],
         None => crate::layer_multi_cmds::selected(s),
     };
     let new_id = s.edit("Convert to Smart Object", |doc, active| {
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index c7fef5ae26..b2153efd03 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -79,14 +79,14 @@ fn accepted(s: &Session, p: &Value) -> HashSet<String> {
     set
 }
 
-fn layers_param(s: &Session, p: &Value) -> Vec<LayerId> {
-    let Some(st) = s.active() else { return Vec::new() };
+fn layers_param(s: &Session, p: &Value) -> Result<Vec<LayerId>> {
+    let st = s.active().ok_or(EngineError::NoDocument)?;
     let all = type_layers(&st.doc);
     if p.get("allLayers").and_then(Value::as_bool) == Some(false) || p.get("layer").is_some() {
-        let active = layer_param(s, p).ok();
-        all.into_iter().filter(|id| Some(*id) == active).collect()
+        let active = layer_param(s, p)?;
+        Ok(all.into_iter().filter(|id| *id == active).collect())
     } else {
-        all
+        Ok(all)
     }
 }
 
@@ -96,7 +96,7 @@ fn list(s: &Session, p: &Value) -> Result<Value> {
     let ok = accepted(s, p);
     let max = p.get("suggestions").and_then(Value::as_u64).unwrap_or(5) as usize;
     let mut out = Vec::new();
-    for id in layers_param(s, p) {
+    for id in layers_param(s, p)? {
         let Some(t) = text(&st.doc, id) else { continue };
         let found = dict.misspellings(t, &ok);
         // Convert every start/end byte offset to a character offset in one pass over the
@@ -147,7 +147,7 @@ fn change_all(s: &mut Session, p: &Value) -> Result<Value> {
     let word = p.get("word").and_then(Value::as_str).filter(|w| !w.is_empty()).ok_or_else(|| bad(cmd, "`changeAll` needs `word`"))?.to_string();
     let to = p.get("replace").and_then(Value::as_str).ok_or_else(|| bad(cmd, "`changeAll` needs `replace`"))?.to_string();
     let doc = s.active().ok_or(EngineError::NoDocument)?.doc.clone();
-    let plan: Vec<(LayerId, Vec<(usize, usize)>)> = layers_param(s, p)
+    let plan: Vec<(LayerId, Vec<(usize, usize)>)> = layers_param(s, p)?
         .into_iter()
         .filter_map(|id| {
             let t = text(&doc, id)?;
@@ -331,6 +331,15 @@ mod tests {
         assert_eq!(text_of(&s, id), "The");
     }
 
+    #[test]
+    fn missing_named_spelling_layer_is_an_error_for_list_and_change_all() {
+        let (mut s, _) = session("Teh");
+        for action in ["list", "changeAll"] {
+            let result = s.execute("edit.checkSpelling", json!({"action": action, "layer": "Removed type", "word": "Teh", "replace": "The"}));
+            assert!(result.is_err(), "{action} silently accepted a missing named layer: {result:?}");
+        }
+    }
+
     #[test]
     fn all_locked_layer_rejects_insert_text_and_spelling_change_without_history() {
         // #4188: Lock All stopped type.edit (#3132) but not these two text edits.
diff --git a/crates/engine/src/session/execute.rs b/crates/engine/src/session/execute.rs
index 2c7ef1ba1c..fd2b57cba9 100644
--- a/crates/engine/src/session/execute.rs
+++ b/crates/engine/src/session/execute.rs
@@ -171,7 +171,7 @@ impl Session {
         if !spec.params.contains("\"layer\":id") {
             return None;
         }
-        let target = LayerId(params.get("layer")?.as_u64()?);
+        let target = commands::explicit_layer(self, params).ok().flatten()?;
         let d = self.active_mut()?;
         d.doc.layer(target)?;
         let active = d.active_layer.replace(target);

From 22402001300d2d9f6421df95f5f350ed8243cfc7 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 01:23:41 -0600
Subject: [PATCH 049/109] Resolve named layers across action replay handlers

---
 crates/engine/src/actions_record/tests.rs        | 10 ++++++++++
 crates/engine/src/cmd/channel_cmds/targeting.rs  |  2 +-
 crates/engine/src/cmd/edit_menu_cmds.rs          |  2 +-
 .../src/cmd/edit_menu_cmds/content_aware.rs      |  4 ++--
 crates/engine/src/cmd/edit_menu_cmds/tests.rs    | 10 ++++++++++
 crates/engine/src/cmd/fill_key_cmds.rs           | 15 +++++++++++++--
 crates/engine/src/cmd/pattern_fill_cmds.rs       | 14 +++++++++++---
 crates/engine/src/cmd/solid_fill_cmds.rs         | 16 +++++++++++++---
 8 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index 18c53b445a..3f53c64c44 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -167,6 +167,16 @@ fn named_nonactive_smart_layer_passes_admission_and_converts_to_layers() {
     assert!(s.active().unwrap().doc.layer(LayerId(top)).is_some());
 }
 
+#[test]
+fn named_filter_mask_target_uses_the_recorded_smart_layer() {
+    let mut s = session();
+    s.execute("type.create", json!({"x": 2, "y": 20, "text": "I", "size": 12})).unwrap();
+    let smart = s.execute("layer.smartObjects.convertToSmartObject", json!({})).unwrap()["layer"].as_u64().unwrap();
+    let name = s.active().unwrap().doc.layer(LayerId(smart)).unwrap().name.clone();
+    new_layer(&mut s, "Top");
+    assert_eq!(crate::channel_cmds::filter_mask_layer(&s, "edit.fill", &json!({"target": "filterMask", "layer": name})), Some(LayerId(smart)));
+}
+
 #[test]
 fn named_nonactive_layer_is_the_one_converted_to_smart() {
     let mut s = session();
diff --git a/crates/engine/src/cmd/channel_cmds/targeting.rs b/crates/engine/src/cmd/channel_cmds/targeting.rs
index 899ecb73f1..13926d1d89 100644
--- a/crates/engine/src/cmd/channel_cmds/targeting.rs
+++ b/crates/engine/src/cmd/channel_cmds/targeting.rs
@@ -269,7 +269,7 @@ pub(crate) fn filter_mask_layer(s: &Session, id: &str, params: &Value) -> Option
     if target_of(params) != Target::FilterMask || !follows_filter_mask(id) {
         return None;
     }
-    params.get("layer").and_then(Value::as_u64).map(LayerId).or_else(|| s.active()?.active_layer)
+    crate::commands::layer_param(s, params).ok()
 }
 
 /// The colour channel pixel commands are limited to, if a single colour channel is targeted.
diff --git a/crates/engine/src/cmd/edit_menu_cmds.rs b/crates/engine/src/cmd/edit_menu_cmds.rs
index cef435e46a..b4287e649e 100644
--- a/crates/engine/src/cmd/edit_menu_cmds.rs
+++ b/crates/engine/src/cmd/edit_menu_cmds.rs
@@ -345,7 +345,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Content-Aware Fill…",
             ["Edit"],
             None,
-            r##"{"sampling":"auto|rectangular|custom","margin":px?,"area":[x,y,w,h]?,"channel":index|name?,"samplingStrokes":[{"mode":"add|subtract","size":px,"points":[[x,y],…]}]? (the workspace's Sampling Brush, after the sampling option's area; added strokes may lie outside the window),"fillEdits":[{"op":"new|add|subtract|intersect","points":[[x,y],…]}|{"op":"expand|contract","by":px}]? (the workspace's lasso edits of the fill area, in order),"sampleAllLayers":bool=false,"colorAdaptation":"default|none|high|veryHigh","rotationAdaptation":"none|low|medium|high|full","scale":bool=false,"mirror":bool=false,"output":"current|new|duplicate","layer":id?=active (the layer filled and sampled),"seed":u64=1}"##,
+            r##"{"sampling":"auto|rectangular|custom","margin":px?,"area":[x,y,w,h]?,"channel":index|name?,"samplingStrokes":[{"mode":"add|subtract","size":px,"points":[[x,y],…]}]? (the workspace's Sampling Brush, after the sampling option's area; added strokes may lie outside the window),"fillEdits":[{"op":"new|add|subtract|intersect","points":[[x,y],…]}|{"op":"expand|contract","by":px}]? (the workspace's lasso edits of the fill area, in order),"sampleAllLayers":bool=false,"colorAdaptation":"default|none|high|veryHigh","rotationAdaptation":"none|low|medium|high|full","scale":bool=false,"mirror":bool=false,"output":"current|new|duplicate","layer":id|name?=active (the layer filled and sampled),"seed":u64=1}"##,
             can_caf,
             content_aware_fill
         ),
diff --git a/crates/engine/src/cmd/edit_menu_cmds/content_aware.rs b/crates/engine/src/cmd/edit_menu_cmds/content_aware.rs
index 928f315bdf..c979d8114b 100644
--- a/crates/engine/src/cmd/edit_menu_cmds/content_aware.rs
+++ b/crates/engine/src/cmd/edit_menu_cmds/content_aware.rs
@@ -383,8 +383,8 @@ fn content_aware_fill_as(s: &mut Session, p: &Value, cmd: &'static str, label: &
     use photocraft_algo::content_aware::fill_owned;
     // The workspace names the layer it opened on: after an Apply to a new layer that one is
     // active, but the fill still samples the original.
-    let id = match p.get("layer").and_then(Value::as_u64) {
-        Some(l) => pixel_layer_id(s, LayerId(l)),
+    let id = match crate::commands::explicit_layer(s, p)? {
+        Some(layer) => pixel_layer_id(s, layer),
         None => pixel_layer(s),
     }
     .map_err(EngineError::Other)?;
diff --git a/crates/engine/src/cmd/edit_menu_cmds/tests.rs b/crates/engine/src/cmd/edit_menu_cmds/tests.rs
index 03cd97679f..fb8dcacdcf 100644
--- a/crates/engine/src/cmd/edit_menu_cmds/tests.rs
+++ b/crates/engine/src/cmd/edit_menu_cmds/tests.rs
@@ -226,6 +226,16 @@ fn blob_session(depth: u32) -> Session {
     s
 }
 
+#[test]
+fn content_aware_fill_uses_a_named_nonactive_source_layer() {
+    let mut s = blob_session(8);
+    let id = s.active().unwrap().active_layer.unwrap();
+    let name = s.active().unwrap().doc.layer(id).unwrap().name.clone();
+    s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+    let result = s.execute("edit.contentAwareFill", json!({"layer": name, "colorAdaptation": "none"})).unwrap();
+    assert_eq!(result["layer"], id.0, "fill must use the recorded source rather than the active layer");
+}
+
 #[test]
 fn content_aware_fill_huge_area_neither_panics_nor_wraps() {
     let mut s = blob_session(8);
diff --git a/crates/engine/src/cmd/fill_key_cmds.rs b/crates/engine/src/cmd/fill_key_cmds.rs
index 16585a33d6..b2135984e2 100644
--- a/crates/engine/src/cmd/fill_key_cmds.rs
+++ b/crates/engine/src/cmd/fill_key_cmds.rs
@@ -18,7 +18,7 @@ use crate::{EngineError, Result, Session};
 /// The fill-key command ids (routed to the Channels panel target like `edit.fill`).
 pub const IDS: [&str; 5] = ["edit.fillForeground", "edit.fillBackground", "edit.fillForegroundPreserve", "edit.fillBackgroundPreserve", "edit.fillHistory"];
 
-const PARAMS: &str = r##"{"layer":id?,"target":"pixels"|"mask"|"filterMask"|"quickMask"|{"channel":i}?}"##;
+const PARAMS: &str = r##"{"layer":id|name?,"target":"pixels"|"mask"|"filterMask"|"quickMask"|{"channel":i}?}"##;
 
 /// The shape or type layer the colour fill keys recolor instead of filling pixels.
 fn target_live_layer(s: &Session, p: &Value) -> Option<LayerId> {
@@ -31,7 +31,7 @@ fn target_live_layer(s: &Session, p: &Value) -> Option<LayerId> {
     if st.channel_view.target == crate::channel_cmds::ChannelTarget::LayerMask {
         return None;
     }
-    let id = if let Some(v) = p.get("layer") { LayerId(v.as_u64()?) } else { st.active_layer? };
+    let id = crate::commands::layer_param(s, p).ok()?;
     let layer = st.doc.layer(id)?;
     if matches!(layer.content, LayerContent::Shape(_) | LayerContent::Text(_)) { Some(id) } else { None }
 }
@@ -411,4 +411,15 @@ mod tests {
         }
         assert_eq!(type_colors(&s), [[1.0, 0.0, 0.0]]);
     }
+
+    #[test]
+    fn fill_key_recolors_a_named_nonactive_type_layer() {
+        let mut s = session();
+        let id = s.execute("type.create", json!({"x": 1, "y": 5, "text": "Hello", "size": 4, "color": "#000000"})).unwrap()["layer"].as_u64().unwrap();
+        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+        s.execute("edit.fillForeground", json!({"layer": name})).unwrap();
+        let LayerContent::Text(text) = &s.active().unwrap().doc.layer(LayerId(id)).unwrap().content else { panic!("type layer was replaced") };
+        assert_eq!(text.char_runs()[0].style.color.to_rgb(), [1.0, 0.0, 0.0]);
+    }
 }
diff --git a/crates/engine/src/cmd/pattern_fill_cmds.rs b/crates/engine/src/cmd/pattern_fill_cmds.rs
index 8372fed530..9c422341fd 100644
--- a/crates/engine/src/cmd/pattern_fill_cmds.rs
+++ b/crates/engine/src/cmd/pattern_fill_cmds.rs
@@ -67,8 +67,8 @@ fn edited(s: &Session, base: &Fill, p: &Value) -> Result<(Fill, Option<Pattern>)
 
 /// The target layer and the fill `p` gives it, checked against the active document.
 fn target(s: &Session, p: &Value) -> Result<(photocraft_doc::LayerId, Fill, Fill, Option<Pattern>)> {
-    if !p.is_object() || p.get("layer").is_some_and(|v| v.as_u64().is_none()) {
-        return Err(bad("params must be an object and layer an unsigned id"));
+    if !p.is_object() {
+        return Err(bad("params must be an object"));
     }
     let st = s.active().ok_or(EngineError::NoDocument)?;
     if let Some(document) = p.get("document")
@@ -139,7 +139,7 @@ pub fn specs() -> Vec<CommandSpec> {
         label: "Pattern Fill…",
         menu: &[],
         shortcut: None,
-        params: r##"{"layer":id? (default active; a Pattern Fill layer),"document":id? (reject a stale dialog),"pattern":id|name?,"patternName":name? (then `pattern` is an id; the name is used when no pattern has that id),"scale":1..1000?,"angle":-180..180?,"link":bool?,"phase":[x,y]? (Snap to Origin: [0,0])}; omitted values keep the layer's"##,
+        params: r##"{"layer":id|name? (default active; a Pattern Fill layer),"document":id? (reject a stale dialog),"pattern":id|name?,"patternName":name? (then `pattern` is an id; the name is used when no pattern has that id),"scale":1..1000?,"angle":-180..180?,"link":bool?,"phase":[x,y]? (Snap to Origin: [0,0])}; omitted values keep the layer's"##,
         enabled: |s| s.active().map(|_| ()).ok_or_else(|| "no document open".into()),
         run: set,
         journal: true,
@@ -165,6 +165,14 @@ mod tests {
         f.clone()
     }
 
+    #[test]
+    fn named_nonactive_pattern_fill_can_be_edited() {
+        let (mut s, id) = session(8);
+        let name = s.active().unwrap().doc.layer(id).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+        assert_eq!(s.execute(SET, json!({"layer": name, "scale": 125})).unwrap()["layer"], id.0);
+    }
+
     #[test]
     fn edit_keeps_masks_is_one_step_and_undoes_at_every_depth() {
         for depth in [8, 16, 32] {
diff --git a/crates/engine/src/cmd/solid_fill_cmds.rs b/crates/engine/src/cmd/solid_fill_cmds.rs
index 85d941760d..5763868d25 100644
--- a/crates/engine/src/cmd/solid_fill_cmds.rs
+++ b/crates/engine/src/cmd/solid_fill_cmds.rs
@@ -45,8 +45,8 @@ pub fn color_param(value: &Value, original: Color, mode: ColorMode) -> Result<Co
 }
 
 fn set(s: &mut Session, p: &Value) -> Result<Value> {
-    if !p.is_object() || p.get("layer").is_some_and(|v| v.as_u64().is_none()) {
-        return Err(bad("params must be an object and layer an unsigned id"));
+    if !p.is_object() {
+        return Err(bad("params must be an object"));
     }
     let st = s.active().ok_or(EngineError::NoDocument)?;
     if let Some(document) = p.get("document")
@@ -84,7 +84,7 @@ pub fn specs() -> Vec<CommandSpec> {
         label: "Solid Color…",
         menu: &[],
         shortcut: None,
-        params: r##"{"layer":id? (default active),"document":id? (reject a stale dialog),"color":"#rrggbb"|"#rrggbbaa"|[r,g,b,a?]|{mode,c:[f32;4],alpha:f32},"cmyk":[c,m,y,k]? (inks 0..1 the colour was picked as: a CMYK document keeps exactly these)}; RGB values without alpha preserve it; stored Color preserves its model and precision"##,
+        params: r##"{"layer":id|name? (default active),"document":id? (reject a stale dialog),"color":"#rrggbb"|"#rrggbbaa"|[r,g,b,a?]|{mode,c:[f32;4],alpha:f32},"cmyk":[c,m,y,k]? (inks 0..1 the colour was picked as: a CMYK document keeps exactly these)}; RGB values without alpha preserve it; stored Color preserves its model and precision"##,
         enabled: |s| s.active().map(|_| ()).ok_or_else(|| "no document open".into()),
         run: set,
         journal: true,
@@ -95,6 +95,16 @@ pub fn specs() -> Vec<CommandSpec> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn named_nonactive_solid_fill_can_be_edited() {
+        let mut s = Session::new();
+        s.execute("file.new", json!({"width": 8, "height": 8})).unwrap();
+        let id = s.execute("layer.newFillLayer.solidColor", json!({"color": "#000000"})).unwrap()["layer"].as_u64().unwrap();
+        let name = s.active().unwrap().doc.layer(photocraft_doc::LayerId(id)).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+        assert_eq!(s.execute(SET, json!({"layer": name, "color": "#ff0000"})).unwrap()["layer"], id);
+    }
+
     /// #8568: CMYK 50/50/50/100 entered for a Solid Color fill in a CMYK document stays exactly
     /// those inks, on creation and on edit, instead of what its sRGB stand-in converts back to
     /// through the document profile. RGB documents ignore the inks.

From 198f9499ad1afc05afe1f40d1eb2368a6d57674a Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 01:31:27 -0600
Subject: [PATCH 050/109] Report missing named action layers without changing
 query errors

---
 crates/engine/src/actions_record/tests.rs |  9 ++++++++-
 crates/engine/src/cmd/type_spell_cmds.rs  | 12 ++++++++++++
 crates/engine/src/session/execute.rs      | 23 ++++++++++++++++-------
 3 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/crates/engine/src/actions_record/tests.rs b/crates/engine/src/actions_record/tests.rs
index 3f53c64c44..0185f7e858 100644
--- a/crates/engine/src/actions_record/tests.rs
+++ b/crates/engine/src/actions_record/tests.rs
@@ -162,9 +162,12 @@ fn named_nonactive_smart_layer_passes_admission_and_converts_to_layers() {
     let smart = s.execute("layer.smartObjects.convertToSmartObject", json!({})).unwrap()["layer"].as_u64().unwrap();
     let name = s.active().unwrap().doc.layer(LayerId(smart)).unwrap().name.clone();
     let top = new_layer(&mut s, "Top");
-    s.execute("layer.smartObjects.convertToLayers", json!({"layer": name})).unwrap();
+    let restored = s.execute("layer.smartObjects.convertToLayers", json!({"layer": name})).unwrap()["layer"].as_u64().unwrap();
     assert!(s.active().unwrap().doc.layer(LayerId(smart)).is_none());
     assert!(s.active().unwrap().doc.layer(LayerId(top)).is_some());
+    assert!(s.active().unwrap().doc.layer(LayerId(restored)).is_some(), "the restored layer is present");
+    let error = s.execute("layer.smartObjects.convertToLayers", json!({"layer": "Removed smart"})).unwrap_err();
+    assert!(error.to_string().contains("Removed smart"), "missing named layer should be identified: {error}");
 }
 
 #[test]
@@ -196,6 +199,10 @@ fn named_nonactive_layer_is_the_one_converted_to_smart() {
     assert!(played.get("failed").is_none(), "{played}");
     assert!(s.active().unwrap().doc.layer(LayerId(replay_target)).is_none(), "replay removes the named source");
     assert!(s.active().unwrap().doc.layer(LayerId(top)).is_some(), "replay keeps the selected top layer");
+    assert!(
+        s.active().unwrap().doc.walk().iter().any(|(_, _, layer)| matches!(layer.content, photocraft_doc::LayerContent::Smart(_))),
+        "replay creates a smart object"
+    );
 }
 
 #[test]
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index b2153efd03..f06bfb15f6 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -340,6 +340,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn named_layer_list_and_change_all_resolve_a_nonactive_layer() {
+        let (mut s, id) = session("Teh");
+        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
+        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
+        let listed = s.execute("edit.checkSpelling", json!({"action": "list", "layer": name})).unwrap();
+        assert_eq!(listed["count"], 1);
+        let changed = s.execute("edit.checkSpelling", json!({"action": "changeAll", "layer": name, "word": "Teh", "replace": "The"})).unwrap();
+        assert_eq!(changed["changed"], 1);
+        assert_eq!(text_of(&s, id), "The");
+    }
+
     #[test]
     fn all_locked_layer_rejects_insert_text_and_spelling_change_without_history() {
         // #4188: Lock All stopped type.edit (#3132) but not these two text edits.
diff --git a/crates/engine/src/session/execute.rs b/crates/engine/src/session/execute.rs
index fd2b57cba9..57d609c5d4 100644
--- a/crates/engine/src/session/execute.rs
+++ b/crates/engine/src/session/execute.rs
@@ -99,7 +99,7 @@ impl Session {
         if let Some(why) = color_channels::refusal(self, id, &run_params) {
             return Err(EngineError::Disabled(id.into(), why));
         }
-        if let Err(why) = self.explicit_layer_enabled(spec, params).unwrap_or_else(|| self.precondition(spec, &run_params)) {
+        if let Err(why) = self.explicit_layer_enabled(spec, params)?.unwrap_or_else(|| self.precondition(spec, &run_params)) {
             return Err(EngineError::Disabled(id.to_string(), why));
         }
         if let Some(why) = self.job_conflict(id, spec.journal) {
@@ -167,19 +167,28 @@ impl Session {
     /// than on the active one, which stays active (#466). A script, action or agent can then
     /// Replace Contents, Rasterize or Merge Down a layer without selecting it first. `None` for
     /// other commands, or without such a layer.
-    pub(crate) fn explicit_layer_enabled(&mut self, spec: &commands::CommandSpec, params: &Value) -> Option<std::result::Result<(), String>> {
+    pub(crate) fn explicit_layer_enabled(&mut self, spec: &commands::CommandSpec, params: &Value) -> Result<Option<std::result::Result<(), String>>> {
         if !spec.params.contains("\"layer\":id") {
-            return None;
+            return Ok(None);
+        }
+        let target = match commands::explicit_layer(self, params) {
+            Ok(Some(target)) => target,
+            Ok(None) => return Ok(None),
+            // Read-only queries keep their own parameter-error contract; recorded commands
+            // must identify a missing named receiver before checking the active layer.
+            Err(_) if !spec.journal => return Ok(None),
+            Err(error) => return Err(error),
+        };
+        let Some(d) = self.active_mut() else { return Ok(None) };
+        if d.doc.layer(target).is_none() {
+            return Ok(None);
         }
-        let target = commands::explicit_layer(self, params).ok().flatten()?;
-        let d = self.active_mut()?;
-        d.doc.layer(target)?;
         let active = d.active_layer.replace(target);
         let r = self.precondition(spec, params);
         if let Some(d) = self.active_mut() {
             d.active_layer = active;
         }
-        Some(r)
+        Ok(Some(r))
     }
 
     /// Apply an undoable edit to the active document.

From c335153361a16a3e7a394052ab8efeb6b1e3b624 Mon Sep 17 00:00:00 2001
From: neversaynv3r <marcos@estelles.es>
Date: Mon, 2 Nov 2026 18:21:32 +0900
Subject: [PATCH 051/109] ATN: keep encoding fallbacks among the top-scoring
 candidates

---
 crates/psd/src/atn.rs      | 24 +++++++++++++++++++++---
 crates/psd/src/codepage.rs | 32 +++++++++++++++++++++++++-------
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/crates/psd/src/atn.rs b/crates/psd/src/atn.rs
index 797845e2fe..4e83cf7222 100644
--- a/crates/psd/src/atn.rs
+++ b/crates/psd/src/atn.rs
@@ -726,10 +726,28 @@ mod tests {
     #[test]
     fn uncertain_guess_warns() {
         let f = parse(&one_action("Set 1", "Action 1", vec![bare(AtnEvent::name("x"), b"\x80\xff\x80")])).unwrap();
-        assert_eq!(f.encoding.as_deref(), Some("windows-1252"));
+        assert_eq!(f.encoding.as_deref(), Some("windows-1251"));
         assert_eq!(f.warnings.len(), 1, "{:?}", f.warnings);
-        assert!(f.warnings[0].contains("windows-1252"), "{:?}", f.warnings);
-        assert_eq!(labels(&f), ["€ÿ€"]);
+        assert!(f.warnings[0].contains("windows-1251"), "{:?}", f.warnings);
+        assert_eq!(labels(&f), ["ЂяЂ"]);
+    }
+
+    #[test]
+    fn unresolved_codepage_tie_keeps_a_top_candidate_and_the_original_bytes() {
+        // GBK 保存 ties with other CJK pages. No Unicode name settles it, but windows-1252
+        // scored lower, so its "±£´æ" must not replace the tied candidates' readable text.
+        let bytes = one_action("Set 1", "Action 1", vec![bare(AtnEvent::name("x"), b"\xb1\xa3\xb4\xe6")]);
+        let f = parse(&bytes).unwrap();
+        assert_eq!(f.encoding.as_deref(), Some("GBK"));
+        assert_eq!(labels(&f), ["保存"]);
+        assert_eq!(f.warnings.len(), 1, "{:?}", f.warnings);
+        assert!(f.warnings[0].contains("read as GBK"), "{:?}", f.warnings);
+        assert_eq!(write(&f).unwrap(), bytes);
+        // Callers can still resolve an ambiguous guess explicitly.
+        let forced = parse_with_encoding(&bytes, Some("windows-1252")).unwrap();
+        assert_eq!(labels(&forced), ["±£´æ"]);
+        assert!(forced.warnings.is_empty(), "{:?}", forced.warnings);
+        assert_eq!(write(&forced).unwrap(), bytes);
     }
 
     #[test]
diff --git a/crates/psd/src/codepage.rs b/crates/psd/src/codepage.rs
index 75e0f7c468..aec13de6bf 100644
--- a/crates/psd/src/codepage.rs
+++ b/crates/psd/src/codepage.rs
@@ -15,7 +15,8 @@
 //! 3. A tie is broken by the script of a hint (text the file stores as UTF-16, so it decodes
 //!    fine): kana → Shift_JIS; Hangul → EUC-KR; Cyrillic → windows-1251; Han → GBK, then
 //!    Big5, then Shift_JIS; Latin letters → windows-1252, then Mac Roman.
-//! 4. Still tied: windows-1252, flagged [`Guess::uncertain`].
+//! 4. Still tied: windows-1252 if it is among them, otherwise the first highest-scoring candidate,
+//!    flagged [`Guess::uncertain`].
 //! 5. Mac Roman must also beat windows-1252 when the Latin-1 symbols that are no letter in
 //!    Mac Roman (© ° « ± …) count as common text (1252 "Größe »" is Mac Roman "Grˆfle ª").
 //!    Otherwise the names are windows-1252, with step 3's hint and step 4's warning.
@@ -39,7 +40,7 @@ pub(crate) const KNOWN_PAIRS: usize = 256;
 pub(crate) struct Guess {
     /// The encoding to decode every legacy name with.
     pub(crate) encoding: &'static Encoding,
-    /// Nothing told the candidates apart; `encoding` is the windows-1252 fallback.
+    /// Nothing settled the highest-scoring candidates' tie; `encoding` is a fallback among them.
     pub(crate) uncertain: bool,
 }
 
@@ -97,7 +98,11 @@ pub(crate) fn guess(legacy: &[&[u8]], hint: &str) -> Guess {
         [only] => Guess { encoding: only, uncertain: false },
         tied => match hinted(hint).iter().find(|enc| tied.contains(enc)) {
             Some(enc) => Guess { encoding: enc, uncertain: false },
-            None => Guess { encoding: WINDOWS_1252, uncertain: true },
+            // A fallback must not discard the scores and choose a lower-scoring page.
+            None => {
+                let encoding = if tied.contains(&WINDOWS_1252) { WINDOWS_1252 } else { tied.first().copied().unwrap_or(WINDOWS_1252) };
+                Guess { encoding, uncertain: true }
+            }
         },
     };
     if picked.encoding != MACINTOSH {
@@ -377,7 +382,7 @@ mod tests {
         assert_eq!(g.encoding, GBK);
         assert!(!g.uncertain);
         assert_eq!(decode(names[0], g.encoding), "保存");
-        assert_eq!(guess(names, "Set 1"), Guess { encoding: WINDOWS_1252, uncertain: true });
+        assert_eq!(guess(names, "Set 1"), Guess { encoding: GBK, uncertain: true });
     }
 
     #[test]
@@ -499,14 +504,27 @@ mod tests {
     fn bytes_no_cjk_page_accepts_still_decode() {
         // 0xFF is invalid in every double-byte candidate; windows-1251 (Ђ я Ђ) and Mac Roman
         // (Ä ˇ Ä) read all three bytes as letters, windows-1252 only one (€ ÿ €). With nothing to
-        // break the tie, the fallback still decodes them.
+        // break the tie, the first highest-scoring candidate still decodes them.
         let names: &[&[u8]] = &[b"\x80\xff\x80"];
         let g = guess(names, "");
-        assert_eq!(g, Guess { encoding: WINDOWS_1252, uncertain: true });
-        assert_eq!(decode(names[0], g.encoding), "€ÿ€");
+        assert_eq!(g, Guess { encoding: WINDOWS_1251, uncertain: true });
+        assert_eq!(decode(names[0], g.encoding), "ЂяЂ");
         assert_eq!(guess(names, "Набор").encoding, WINDOWS_1251);
     }
 
+    #[test]
+    fn uncertain_fallback_stays_among_the_highest_scoring_candidates() {
+        // Mac Roman "Ändern": Mac Roman and windows-1251 both score every non-ASCII byte
+        // as a letter. Windows-1252 reads "€ndern", so it must not win their unresolved tie.
+        let names: &[&[u8]] = &[b"\x80ndern"];
+        for hint in ["Set 1", "保存"] {
+            let g = guess(names, hint);
+            assert!([MACINTOSH, WINDOWS_1251].contains(&g.encoding), "{hint}: {g:?}");
+            assert!(g.uncertain, "{hint}: {g:?}");
+            assert_eq!(score(g.encoding, names[0]), (1, 1));
+        }
+    }
+
     #[test]
     fn empty_or_utf8_input_is_utf8() {
         let g = guess(&[], "");

From 7dadc3177dc7fa9b321438b44e4dad80e311d829 Mon Sep 17 00:00:00 2001
From: Hector Villarreal <hectorviov@gmail.com>
Date: Sat, 31 Oct 2026 00:13:38 -0600
Subject: [PATCH 052/109] Layers panel: filter by Color, as in Photoshop
 (#5898)

The Layers panel's filter row gains Color after Kind, Name and Mode. Like
Photoshop's, it filters at once (by no colour at first) and lists the layers
whose label is the chosen colour; the colour menu is None plus the label
colours in Photoshop's order. ui.set's layerFilter takes "by": "color" and a
"color" label id.

Fixes #5898

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/panels/layer_filter_ui.rs  | 54 +++++++++++++------
 .../src/panels/layer_filter_ui/tests.rs       | 23 ++++++++
 crates/ui-egui/src/state.rs                   |  4 ++
 docs/control-protocol.md                      |  2 +-
 4 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui.rs b/crates/ui-egui/src/panels/layer_filter_ui.rs
index fd035f3284..d9d90452a2 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui.rs
@@ -1,10 +1,10 @@
 //! The Layers panel's filter row (#5048): a filter-type dropdown, as in Photoshop, then the
 //! controls for that type. Kind toggles layer kinds, Name matches part of the layer name, Mode
-//! picks one blend mode. The criteria live in `UiState` (`layer_filter*`), so the control channel
+//! picks one blend mode, Color one layer colour label (#5898). The criteria live in `UiState` (`layer_filter*`), so the control channel
 //! can read and set them.
 
 use photocraft_color::BlendMode;
-use photocraft_doc::{Layer, LayerContent};
+use photocraft_doc::{LabelColor, Layer, LayerContent};
 use serde::{Deserialize, Serialize};
 
 use crate::state::UiState;
@@ -18,6 +18,7 @@ pub enum FilterBy {
     Kind,
     Name,
     Mode,
+    Color,
 }
 
 /// The filter criteria, copied out of `UiState` for one frame of the Layers panel.
@@ -28,20 +29,27 @@ pub struct Filter {
     /// As typed; matched trimmed and ignoring case.
     pub name: String,
     pub mode: BlendMode,
+    pub color: LabelColor,
 }
 
 impl Filter {
     pub fn of(ui: &UiState) -> Self {
-        Self { by: ui.layer_filter_by, kinds: ui.layer_filter.clone(), name: ui.layer_filter_name.clone(), mode: ui.layer_filter_mode }
+        Self {
+            by: ui.layer_filter_by,
+            kinds: ui.layer_filter.clone(),
+            name: ui.layer_filter_name.clone(),
+            mode: ui.layer_filter_mode,
+            color: ui.layer_filter_color,
+        }
     }
 
-    /// Whether the panel is filtered. Like Photoshop, Mode always filters (by Normal at first);
-    /// Kind and Name only once a kind is toggled or some text is typed.
+    /// Whether the panel is filtered. Like Photoshop, Mode and Color always filter (by Normal and
+    /// by no colour at first); Kind and Name only once a kind is toggled or some text is typed.
     pub fn active(&self) -> bool {
         match self.by {
             FilterBy::Kind => !self.kinds.is_empty(),
             FilterBy::Name => !self.name.trim().is_empty(),
-            FilterBy::Mode => true,
+            FilterBy::Mode | FilterBy::Color => true,
         }
     }
 
@@ -54,6 +62,7 @@ impl Filter {
             FilterBy::Kind => self.kinds.iter().any(|k| k == kind(l)),
             FilterBy::Name => l.name.to_lowercase().contains(&self.name.trim().to_lowercase()),
             FilterBy::Mode => l.blend == self.mode,
+            FilterBy::Color => l.label == self.color,
         }
     }
 }
@@ -61,18 +70,18 @@ impl Filter {
 /// The kinds the Kind filter toggles.
 pub const KINDS: [&str; 5] = ["pixel", "adjustment", "type", "shape", "smart"];
 
-/// `ui.set {layerFilter: {by?, kinds?, name?, mode?}}`: `current` with the given fields replaced,
-/// or an error naming the bad field (nothing changes then). `by` is `kind`, `name` or `mode`;
-/// `kinds` a list of [`KINDS`]; `mode` a blend mode name such as `Multiply` or `Pass Through`.
+/// `ui.set {layerFilter: {by?, kinds?, name?, mode?, color?}}`: `current` with the given fields
+/// replaced, or an error naming the bad field (nothing changes then). `by` is `kind`, `name`,
+/// `mode` or `color`; `kinds` a list of [`KINDS`]; `mode` a blend mode name such as `Multiply` or
+/// `Pass Through`; `color` a label colour id (`none`, `red`, … `gray`, [`LabelColor::id`]).
 pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, String> {
     let Some(o) = v.as_object() else { return Err("layerFilter must be an object".into()) };
-    if let Some(k) = o.keys().find(|k| !["by", "kinds", "name", "mode"].contains(&k.as_str())) {
-        return Err(format!("unknown layerFilter field `{k}` (fields: by, kinds, name, mode)"));
+    if let Some(k) = o.keys().find(|k| !["by", "kinds", "name", "mode", "color"].contains(&k.as_str())) {
+        return Err(format!("unknown layerFilter field `{k}` (fields: by, kinds, name, mode, color)"));
     }
-    let mut f =
-        Filter { by: current.layer_filter_by, kinds: current.layer_filter.clone(), name: current.layer_filter_name.clone(), mode: current.layer_filter_mode };
+    let mut f = Filter::of(current);
     if let Some(by) = o.get("by") {
-        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name or mode".to_string())?;
+        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name, mode or color".to_string())?;
     }
     if let Some(kinds) = o.get("kinds") {
         let list = kinds.as_array().ok_or("layerFilter.kinds must be a list")?;
@@ -95,6 +104,13 @@ pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, Strin
             .filter(|m| *m == BlendMode::PassThrough || BlendMode::LAYER_MODES.contains(m))
             .ok_or_else(|| format!("layerFilter.mode: unknown blend mode `{name}`"))?;
     }
+    if let Some(color) = o.get("color") {
+        let id = color.as_str().ok_or("layerFilter.color must be a label colour id")?;
+        f.color = LabelColor::ALL.into_iter().find(|c| c.id() == id).ok_or_else(|| {
+            let ids: Vec<&str> = LabelColor::ALL.iter().map(|c| c.id()).collect();
+            format!("layerFilter.color: unknown colour `{id}` (colours: {})", ids.join(", "))
+        })?;
+    }
     Ok(f)
 }
 
@@ -104,6 +120,7 @@ pub fn apply(ui: &mut UiState, f: Filter) {
     ui.layer_filter = f.kinds;
     ui.layer_filter_name = f.name;
     ui.layer_filter_mode = f.mode;
+    ui.layer_filter_color = f.color;
 }
 
 /// The kind filter's name for `l`'s content ("" for groups, which no kind matches).
@@ -122,7 +139,7 @@ fn kind(l: &Layer) -> &'static str {
 pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     ui.horizontal(|ui| {
         ui.spacing_mut().item_spacing.x = 2.0;
-        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode"))];
+        let by = [(FilterBy::Kind, tl!("Kind")), (FilterBy::Name, tl!("Name")), (FilterBy::Mode, tl!("Mode")), (FilterBy::Color, tl!("Color"))];
         widgets::dropdown(ui, "layer-filter-by", tl!("Kind"), &mut app.ui.layer_filter_by, &by, 64.0);
         ui.add_space(4.0);
         match app.ui.layer_filter_by {
@@ -153,6 +170,13 @@ pub fn bar(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
                 let width = ui.available_width().max(96.0);
                 widgets::dropdown(ui, "layer-filter-mode", tl!("Mode"), &mut app.ui.layer_filter_mode, &modes, width);
             }
+            FilterBy::Color => {
+                // Photoshop's list: None, then the label colours in the Layers panel menu's order.
+                let colors: Vec<(LabelColor, &str)> =
+                    LabelColor::ALL.into_iter().map(|c| (c, if c == LabelColor::None { tl!("None") } else { tl!(c.label()) })).collect();
+                let width = ui.available_width().max(96.0);
+                widgets::dropdown(ui, "layer-filter-color", tl!("Color"), &mut app.ui.layer_filter_color, &colors, width);
+            }
         }
     });
 }
diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index 89e1a6a0b9..7e6b841de8 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -136,3 +136,26 @@ fn the_dropdown_switches_the_panel_between_filter_types() {
     h.run_steps(4);
     assert_eq!(drawn(&h), ["ink notes"]);
 }
+
+/// #5898: Photoshop's Color filter lists the layers with one colour label; it filters at once,
+/// by no colour (None) at first, like Mode. Agents set it with `layerFilter.color`.
+#[test]
+fn the_color_filter_lists_one_label() {
+    let mut s = session();
+    let ink = layer(&s.active().unwrap().doc, "Ink");
+    let sheets = layer(&s.active().unwrap().doc, "Sheets");
+    // A group's colour goes to its layers too (Photoshop), so the group first, then Ink inside it.
+    s.execute("layer.setLabelColor", json!({"layer": sheets, "color": "seafoam"})).unwrap();
+    s.execute("layer.setLabelColor", json!({"layer": ink, "color": "red"})).unwrap();
+    let doc = &s.active().unwrap().doc;
+    let by_color = |c: photocraft_doc::LabelColor| Filter::of(&UiState { layer_filter_by: FilterBy::Color, layer_filter_color: c, ..UiState::default() });
+    assert!(by_color(photocraft_doc::LabelColor::None).active(), "Color filters at once, as in Photoshop");
+    assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::Red)), ["Ink"]);
+    assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::Seafoam)), ["Sheets", "Paper"]);
+    assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::None)), ["ink notes", "Background"]);
+    // Over the control channel.
+    let f = super::patched(&UiState::default(), &json!({"by": "color", "color": "red"})).unwrap();
+    assert_eq!((f.by, f.color), (FilterBy::Color, photocraft_doc::LabelColor::Red));
+    assert!(super::patched(&UiState::default(), &json!({"color": "crimson"})).unwrap_err().contains("crimson"));
+    assert!(super::patched(&UiState::default(), &json!({"color": 2})).is_err());
+}
diff --git a/crates/ui-egui/src/state.rs b/crates/ui-egui/src/state.rs
index c18a418c4c..6a82adb77f 100644
--- a/crates/ui-egui/src/state.rs
+++ b/crates/ui-egui/src/state.rs
@@ -364,6 +364,9 @@ pub struct UiState {
     /// Layers panel blend-mode filter.
     #[serde(default = "default_layer_filter_mode")]
     pub layer_filter_mode: photocraft_color::BlendMode,
+    /// Layers panel colour filter (#5898): the label colour listed (None: layers without one).
+    #[serde(default)]
+    pub layer_filter_color: photocraft_doc::LabelColor,
     /// Actions panel: which row is selected and which are expanded. The list lives on the session.
     #[serde(default)]
     pub actions: crate::actions::ActionsUi,
@@ -575,6 +578,7 @@ impl Default for UiState {
             layer_filter_by: Default::default(),
             layer_filter_name: String::new(),
             layer_filter_mode: default_layer_filter_mode(),
+            layer_filter_color: Default::default(),
             pen: None,
             pen_doc: None,
             stroke_editor: None,
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 7c5f4f2c24..8e1c525008 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -54,7 +54,7 @@ The transport is `apps/photocraft/src/control_server.rs`, and the handlers are i
 - `ui.set` also accepts `camTransformOnDrop` (boolean), the Content-Aware Move tool's Transform On Drop checkbox: a drop then puts a scale/rotate box on the patch (`ui.inspect` › `camTransform`: its document/revision, drag `offset` and `frame`), driven with `ui.pointer` (handles as Free Transform's; outside the box rotates), committed with `ui.key Enter` (one `paint.contentAwareMove` with `scaleX`, `scaleY`, `rotate`) or dropped with `Escape`.
 - `ui.set` also accepts `tileGrid` (boolean), a developer overlay of the active layer's storage tiles: the tile grid over the document, every stored tile filled and labelled `tx,ty`, tiles with identical pixels in a shared colour and unique ones in blue. It has no menu item and View › Extras doesn't hide it. `ui.inspect` reports it as `view.tile_grid`.
 - `ui.set` also accepts `strokeTrace` (`true`, `false`, `"stderr"` or `"off"`): turn the stroke latency trace on or off at runtime; each stroke's summary is in `ui.inspect` `perf.strokeTrace`. A CSV file of every frame is set only at launch (`PHOTOCRAFT_STROKE_TRACE=<file.csv>` / `--stroke-trace <file.csv>`): the control channel doesn't write files outside the automation write root
-- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?}`, any subset. `by` is `kind`, `name` or `mode` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`). Kind and Name filter only once a kind is on or text is typed; Mode always filters, by Normal at first, as in Photoshop. Fields left out keep their value; a bad one is an error and changes nothing.
+- `ui.set` also accepts `layerFilter` (#5048), the Layers panel filter row: `{by?, kinds?, name?, mode?, color?}`, any subset. `by` is `kind`, `name`, `mode` or `color` (the filter-type dropdown); `kinds` lists the Kind toggles that are on (`pixel`, `adjustment`, `type`, `shape`, `smart`); `name` matches part of a layer name, ignoring case; `mode` is a blend mode name (`Multiply`, `Pass Through`); `color` is a layer colour label id (`none`, `red`, `orange`, `yellow`, `green`, `seafoam`, `blue`, `indigo`, `magenta`, `fuchsia`, `violet`, `gray`; #5898). Kind and Name filter only once a kind is on or text is typed; Mode and Color always filter, by Normal and by no colour at first, as in Photoshop. Fields left out keep their value; a bad one is an error and changes nothing.
 - `ui.set` also accepts the Histogram panel: `histogramPanel` `{view?, channel?, showChannelsInColor?, showStatistics?, source?}` (any subset, kept with the preferences): `view` is `compact`, `expanded` or `allChannels`; `channel` is `composite`, `red`, `green`, `blue`, `cyan`, `magenta`, `yellow`, `black`, `a`, `b`, `luminosity` or `colors` (one the document's mode lacks shows as its composite); `source` is `entireImage`, `selectedLayer` or `adjustmentComposite` (Entire Image is counted in Compact View, when the document has one layer, or when no adjustment layer is selected for Adjustment Composite). `histogramRange` is `[from, to]` (levels 0..255) or `null`: the dragged tonal range whose Count and Percentile the statistics show. `histogramRefresh: true` is Uncached Refresh: the current state is recounted at cache level 1. `ui.inspect` › `histogram` reports the options, the channel and source as they apply, the channels the document offers, whether the shown histogram is `current` (counted for the document's revision, source and cache level the panel wants now), its `cacheLevel`, `maxCacheLevel` (Preferences › Performance › Cache Levels), `preview` (an adjustment's preview is counted) and `stats` (`mean`, `stdDev`, `median`, `pixels`, `level`, `count`, `percentile`, `clipped` percent at 0 and 255). Histograms are counted while the panel is shown.
 - Each painting tool keeps its own brush, as in Photoshop: `tools.setBrush` and `ui.set {brushSize}` change the active tool's brush, and switching tools swaps in that tool's own (size, hardness, mode, opacity, flow, dynamics, smoothing). A tool used for the first time starts from the brush in hand. The colours, the erase flag and the stroke seed stay shared. So `ui.set {tool: "eraser", brushSize: 12}` sets the Eraser's size, and `ui.set {tool: "brush"}` afterwards brings the Brush's own size back.
 - Brush Pose's `pose.overrideTiltX` and `pose.overrideTiltY` are independent booleans. For example, `engine.execute {"command":"tools.setBrush","params":{"pose":{"enabled":true,"tiltX":45,"overrideTiltX":true,"overrideTiltY":false}}}` fixes X at 45° while Y follows the stylus. Pose tilts are degrees (±90); the Brush Settings panel displays percentages (±100). Old stored `overrideTilt` values migrate to both axes. In command patches, `overrideTilt` sets both axes unless an explicit axis field in the same patch overrides it. `brush.get` includes both axis flags and the legacy combined readback (`overrideTilt` is true only when both flags are true). Axis-only journals omit that derived combined key so replay retains the other axis. Present flag values must be booleans; null and other types return an error.

From 7439eb7179f74c0250da7ac5790444368a8b54ae Mon Sep 17 00:00:00 2001
From: Hector Villarreal <hectorviov@gmail.com>
Date: Sat, 31 Oct 2026 00:59:45 -0600
Subject: [PATCH 053/109] Layers filter: drive the Color filter through ui.set
 in the control test (CodeRabbit nitpick on layer_filter_ui/tests.rs:153-161)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/control/tests.rs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/crates/ui-egui/src/control/tests.rs b/crates/ui-egui/src/control/tests.rs
index 9868624183..af1c32787f 100644
--- a/crates/ui-egui/src/control/tests.rs
+++ b/crates/ui-egui/src/control/tests.rs
@@ -907,6 +907,10 @@ fn ui_set_drives_the_layers_panel_filter() {
         assert_eq!(r["ok"], false, "{bad} → {r}");
         assert_eq!(app.ui.layer_filter_by, FilterBy::Mode, "{bad} changed nothing");
     }
+    // #5898: the Color filter through the same path.
+    let ok = call(&mut app, &ctx, "ui.set", json!({"layerFilter": {"by": "color", "color": "red"}}));
+    assert_eq!(ok["ok"], true, "{ok}");
+    assert_eq!((app.ui.layer_filter_by, app.ui.layer_filter_color), (FilterBy::Color, photocraft_doc::LabelColor::Red));
 }
 
 #[test]

From 1ce90f0ae087071f77b628896e86ff40d58c42e8 Mon Sep 17 00:00:00 2001
From: Hector Villarreal <hectorviov@gmail.com>
Date: Sat, 31 Oct 2026 22:03:38 -0600
Subject: [PATCH 054/109] Tests: Color filter with no matching layers and an
 unknown colour through ui.set (FredApps review)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/control/tests.rs                | 1 +
 crates/ui-egui/src/panels/layer_filter_ui/tests.rs | 1 +
 2 files changed, 2 insertions(+)

diff --git a/crates/ui-egui/src/control/tests.rs b/crates/ui-egui/src/control/tests.rs
index af1c32787f..6670f2840c 100644
--- a/crates/ui-egui/src/control/tests.rs
+++ b/crates/ui-egui/src/control/tests.rs
@@ -900,6 +900,7 @@ fn ui_set_drives_the_layers_panel_filter() {
         json!({"layerFilter": {"kinds": "pixel"}}),
         json!({"layerFilter": {"name": 3}}),
         json!({"layerFilter": {"mode": "Nonsense"}}),
+        json!({"layerFilter": {"color": "crimson"}}),
         json!({"layerFilter": {"by": "kind", "extra": true}}),
         json!({"layerFilter": {"by": "kind"}, "tileGrid": "yes"}),
     ] {
diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index 7e6b841de8..66621cd840 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -153,6 +153,7 @@ fn the_color_filter_lists_one_label() {
     assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::Red)), ["Ink"]);
     assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::Seafoam)), ["Sheets", "Paper"]);
     assert_eq!(listed(doc, &by_color(photocraft_doc::LabelColor::None)), ["ink notes", "Background"]);
+    assert!(listed(doc, &by_color(photocraft_doc::LabelColor::Blue)).is_empty(), "a colour no layer has lists nothing");
     // Over the control channel.
     let f = super::patched(&UiState::default(), &json!({"by": "color", "color": "red"})).unwrap();
     assert_eq!((f.by, f.color), (FilterBy::Color, photocraft_doc::LabelColor::Red));

From 7be3957476219723aca1b0c159f218bb9b4a3643 Mon Sep 17 00:00:00 2001
From: Hector Villarreal <hectorviov@gmail.com>
Date: Sat, 31 Oct 2026 22:35:48 -0600
Subject: [PATCH 055/109] Docs: UI parity lists the Layers panel's Color filter
 (CodeRabbit review on docs/ui-parity.md:248)

The filter-type dropdown row now reads Kind, Name, Mode and Color, the other five missing; status
line and revision history updated. No percentage changed; the scorecard has no row for it
(`cargo xtask scorecard` leaves docs/scorecard.md as it was).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ui-parity.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/ui-parity.md b/docs/ui-parity.md
index 56f26760e1..21acabb29e 100644
--- a/docs/ui-parity.md
+++ b/docs/ui-parity.md
@@ -1,6 +1,6 @@
 # UI parity: tools, handles, modifiers and feel
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-01 · **Change:** minor (11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; Shape Fill/Stroke popover as Photoshop's, every colour swatch opens the full Color Picker with a live preview; the text and gradient stop Color Pickers show the picked colour on the canvas before OK, #5530; selected colour sets edit drawing, tone and supported filters; geometry remains open; a paragraph box that can't hold its text enlarges its lower-right handle and shows a black + in it, as the reference application; Free Transform of several selected layers, #6501; Path Operations fixes: the first component keeps combining, a hidden component selection is left alone, a dragged live shape stays live, a refused Pen draft ends once; Pen, Freeform Pen, Curvature Pen and Path Selection Path Operations menu, which changes selected components, `+` / `-` keys, #1397; the Pen carries on an open shape or vector mask path; selection-aware font controls, pending caret fonts and focused commit, plus direct font-name editing with a compact no-match message, #9338; New Group dialog and button modifiers; new layers go into an open active group and join a clipping mask, except that type, shapes, pastes and placed files go above a group whose lock would refuse them; Color panel Hue and Brightness Cube show the out-of-gamut ⚠ and nearest printable colour when the field is at least 53 pt tall, #8672; Art History Brush in the History group of the Y flyout, partial, TOOL-213-20, #1610; Histogram panel: Compact / Expanded / All Channels views, Luminosity and Colors channels, Source, range statistics, Uncached Refresh, live adjustment overlay, Cache Levels preference; the font menu opens on the current family, marked in the recent group when it is a recent one, #9160; Type options bar alignment and direction follow the target paragraph; a swatch click recolours selected type and shape layers with any tool, #9238; UI scale presets done: 105–120% steps, #3222; ⇧⌥ blend mode letters; painting tool Mode menus; ⌥ + an adjustment's shortcut reopens it at its last settings, ⌥⌘L / ⌥⌘M, #8900; Crop default mode: moving the image under the box snaps the frame's edges and centre, #8580; View › Extras hides the Move transform controls, #6699; adjustment clipping stays visible in compact Properties, #5231; Color panel modes from its panel menu, the same in every theme, UI-217-17, #6000; a picked colour recolours the selected type and shapes; Hand tool ⌘ / ⌥ are Zoom In / Zoom Out while held, #6434; the wheel steps value fields, #5473; a dragged guide shows its X or Y beside the pointer, #7680; Type options bar "T" icon scrubs the font size, #6437; Move tool: dragged selected pixels take their own outline as the selection, #7538; artboard backgrounds remain below child Free Transform previews; ⌫/Delete removes the selected smart filter, #4751; Object Finder foreground/background discrimination (#6548); rounded triangle, polygon and star corners; shape Fill/Stroke popovers accept hex RGB values, #6176; a guide let go over either ruler is removed, #6286; Crop rows corrected: saved crop presets and Delete Cropped Pixels off are done, #6562; marching ants in device pixels, #7489; Animated Zoom: holding the Zoom tool zooms continuously, #6210; shape Density and Feather, TOOL-214-12, #5846; Pen Auto Add/Delete on the path being drawn, #6140; Show Transform Controls frames every selected layer; guide keys and clicks; menu bar from the keyboard, #4988; Crop tool Content-Aware Fill; on-canvas corner radius widgets, TOOL-214-12; Curvature Pen edits the active path; Clip Thumbnails to Layer Bounds; Pen ⇧ 45°; last selected tool restored at launch; Layers panel filter-type dropdown with Kind, Name and Mode, #5048; Free Transform box and marching ants follow the selection, #5297; History: the trash deletes the selected snapshot, rows drag onto the trash, #5324; smart filter reordering by drag; smart object perspective row corrected to done, #426; Free Transform H/V skew fields; toolbar tool shortcuts can be reassigned; ⇧-dragged guides land on ruler ticks; layer and selection keys; tool keys; spring-loaded tool letters; type formatting keys; Pen Auto Add/Delete, #4144; smart filter rows; stale missing-tool rows corrected: Color Replacement, Red Eye and the Add/Delete Anchor Point pair are live toolbar tools, Frame landed; no percentage changed; selection-modifier and ⌥-wheel rows match their tests; Properties › Transform shows a shape's path geometry, without its stroke) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-01 · **Change:** minor (Layers panel filter by Color, #5898; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; Shape Fill/Stroke popover as Photoshop's, every colour swatch opens the full Color Picker with a live preview; the text and gradient stop Color Pickers show the picked colour on the canvas before OK, #5530; selected colour sets edit drawing, tone and supported filters; geometry remains open; a paragraph box that can't hold its text enlarges its lower-right handle and shows a black + in it, as the reference application; Free Transform of several selected layers, #6501; Path Operations fixes: the first component keeps combining, a hidden component selection is left alone, a dragged live shape stays live, a refused Pen draft ends once; Pen, Freeform Pen, Curvature Pen and Path Selection Path Operations menu, which changes selected components, `+` / `-` keys, #1397; the Pen carries on an open shape or vector mask path; selection-aware font controls, pending caret fonts and focused commit, plus direct font-name editing with a compact no-match message, #9338; New Group dialog and button modifiers; new layers go into an open active group and join a clipping mask, except that type, shapes, pastes and placed files go above a group whose lock would refuse them; Color panel Hue and Brightness Cube show the out-of-gamut ⚠ and nearest printable colour when the field is at least 53 pt tall, #8672; Art History Brush in the History group of the Y flyout, partial, TOOL-213-20, #1610; Histogram panel: Compact / Expanded / All Channels views, Luminosity and Colors channels, Source, range statistics, Uncached Refresh, live adjustment overlay, Cache Levels preference; the font menu opens on the current family, marked in the recent group when it is a recent one, #9160; Type options bar alignment and direction follow the target paragraph; a swatch click recolours selected type and shape layers with any tool, #9238; UI scale presets done: 105–120% steps, #3222; ⇧⌥ blend mode letters; painting tool Mode menus; ⌥ + an adjustment's shortcut reopens it at its last settings, ⌥⌘L / ⌥⌘M, #8900; Crop default mode: moving the image under the box snaps the frame's edges and centre, #8580; View › Extras hides the Move transform controls, #6699; adjustment clipping stays visible in compact Properties, #5231; Color panel modes from its panel menu, the same in every theme, UI-217-17, #6000; a picked colour recolours the selected type and shapes; Hand tool ⌘ / ⌥ are Zoom In / Zoom Out while held, #6434; the wheel steps value fields, #5473; a dragged guide shows its X or Y beside the pointer, #7680; Type options bar "T" icon scrubs the font size, #6437; Move tool: dragged selected pixels take their own outline as the selection, #7538; artboard backgrounds remain below child Free Transform previews; ⌫/Delete removes the selected smart filter, #4751; Object Finder foreground/background discrimination (#6548); rounded triangle, polygon and star corners; shape Fill/Stroke popovers accept hex RGB values, #6176; a guide let go over either ruler is removed, #6286; Crop rows corrected: saved crop presets and Delete Cropped Pixels off are done, #6562; marching ants in device pixels, #7489; Animated Zoom: holding the Zoom tool zooms continuously, #6210; shape Density and Feather, TOOL-214-12, #5846; Pen Auto Add/Delete on the path being drawn, #6140; Show Transform Controls frames every selected layer; guide keys and clicks; menu bar from the keyboard, #4988; Crop tool Content-Aware Fill; on-canvas corner radius widgets, TOOL-214-12; Curvature Pen edits the active path; Clip Thumbnails to Layer Bounds; Pen ⇧ 45°; last selected tool restored at launch; Layers panel filter-type dropdown with Kind, Name and Mode, #5048; Free Transform box and marching ants follow the selection, #5297; History: the trash deletes the selected snapshot, rows drag onto the trash, #5324; smart filter reordering by drag; smart object perspective row corrected to done, #426; Free Transform H/V skew fields; toolbar tool shortcuts can be reassigned; ⇧-dragged guides land on ruler ticks; layer and selection keys; tool keys; spring-loaded tool letters; type formatting keys; Pen Auto Add/Delete, #4144; smart filter rows; stale missing-tool rows corrected: Color Replacement, Red Eye and the Add/Delete Anchor Point pair are live toolbar tools, Frame landed; no percentage changed; selection-modifier and ⌥-wheel rows match their tests; Properties › Transform shows a shape's path geometry, without its stroke) · **Target:** Adobe Photoshop 2026
 
 How PhotoCraft's direct manipulation compares with Photoshop 2026 (27.11.0): the toolbox, the
 handles and modifier keys of each gesture, nudging, snapping, numeric precision, navigation,
@@ -256,7 +256,7 @@ Paragraph; the rest open as in-app floating windows.
 | New layers (New Layer/Group, adjustment, fill, type, shape, paste, place…) go in as the top layer of an open active group (or an artboard the new content is on), above a closed one; type, shapes, pastes, placed files and frames go above a group whose lock (all, pixels, transparency or position) would refuse them; a new frame starts closed | done | `layer_place.rs`, `layer_place_tests.rs` |
 | A new layer or group inside a clipping mask joins it (clipped when the layer above its slot is), so the clipped layers keep their base | done | `layer_place_tests.rs` (#2203) |
 | Layers panel New Layer button: ⌘-click adds the layer below the active one (never under the Background) | done | `layer_place_tests.rs`, `new_group_button_tests.rs` |
-| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name and Mode; the other six missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048) |
+| Layers panel filter-type dropdown (Kind, Name, Effect, Mode, Attribute, Color, Smart Object, Selected, Artboard) | partial | Kind, Name, Mode and Color; the other five missing. `layer_filter_ui.rs`, `ui.set {layerFilter}` (#5048, #5898) |
 | Adjustment scope: clipping control visible above tall Properties editors in a compact dock | done (2026-10-21) | `panels.rs`, `clipping_indicator_tests.rs`; #5231; stack-wide default retained |
 | Smart filter rows: click selects, drag onto another smart object moves, ⌥-drag copies, drag onto Delete removes; with a row selected, the Delete button and the ⌫/Delete key remove that filter, not the smart object | done | `smart_ui.rs`, `layer.smartFilter.transfer` (#4271), `smart_ui::keys` (#4751) |
 | Layers panel: Clip Thumbnails to Layer Bounds (panel menu, `interface.clipThumbnailsToLayerBounds`) | done (2026-10-12) | `layer_thumb_bounds_tests.rs`; #4281. Thumbnail size and the Panel Options dialog to come |
@@ -267,6 +267,7 @@ Paragraph; the rest open as in-app floating windows.
 | Date | Change | Summary |
 |---|---|---|
 | 2026-11-01 | minor | Every preference takes effect: 11 of 183 do nothing (was 12); Graphics Adapter always worked, but startup read it by raw JSON key, which the scorecard audit can't see |
+| 2026-10-31 | minor | Layers panel filter-type dropdown: Color filters by the layers' label colour (#5898); Kind, Name, Mode and Color, the other five missing; no percentage changed |
 | 2026-10-29 | minor | Paragraph box overflow: text a box can't hold enlarges the box's lower-right handle and shows a black + in it, as the reference application does (#8311); agents read `typeBoxOverflow` in `ui.inspect`. Not a new command, so no percentage changed |
 | 2026-10-28 | minor | The text and gradient stop Color Pickers preview the picked colour on the canvas before OK, as Photoshop's do (#5530); no percentage changed |
 | 2026-10-27 | minor | Shape Fill/Stroke popover as Photoshop's (paint types, Color Picker button, Recently Used Colors, swatch folders, with the Gradient tab) and every colour swatch opens the full Color Picker; rows added (partial, done); Recently Used Colors is a new preference, so 12 of 183 do nothing; no percentage changed; 2026-10-30: the swatches preview live while their Color Picker is open |

From f4a87783a3b82d27d7d14d583ac47720c8f3eb28 Mon Sep 17 00:00:00 2001
From: Hector Villarreal <hectorviov@gmail.com>
Date: Sat, 31 Oct 2026 22:41:19 -0600
Subject: [PATCH 056/109] Docs: ui.set layerFilter lists the color filter
 (CodeRabbit review on crates/automation/src/server.rs:351)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/automation/src/server.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/crates/automation/src/server.rs b/crates/automation/src/server.rs
index 544dbc90f1..b6c311cd6e 100644
--- a/crates/automation/src/server.rs
+++ b/crates/automation/src/server.rs
@@ -348,9 +348,9 @@ pub struct UiSetParams {
     /// dashes, dashOffset and opacity; null disables the stroke). Shape stroke fields use
     /// `shape.edit` names and units; colour comes from `tools.setColors`. camTransformOnDrop (bool,
     /// the Content-Aware Move tool's Transform On Drop). tileGrid (bool, a developer overlay of the
-    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name" or
-    /// "mode"), kinds (a list of layer kinds), name (matches part of the layer name) and mode (a
-    /// blend mode name) for the Layers panel filter). strokeTrace (true, false, "stderr" or "off":
+    /// active layer's storage tiles). layerFilter (an object patching by ("kind", "name", "mode"
+    /// or "color"), kinds (a list of layer kinds), name (matches part of the layer name), mode (a
+    /// blend mode name) and color (a layer colour label, or "none") for the Layers panel filter). strokeTrace (true, false, "stderr" or "off":
     /// the stroke latency trace at runtime; a CSV file is set at launch with --stroke-trace, not
     /// over this channel). updatesOpen (bool, the Help › Check for Updates window).
     /// histogramPanel (an object patching view ("compact", "expanded" or "allChannels"), channel

From 945cf2218d67b6c748329bd463c352c0c00198f4 Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Mon, 2 Nov 2026 18:29:48 +0100
Subject: [PATCH 057/109] Crop with Delete Cropped Pixels off turns the
 Background into Layer 0 (#10867)

A crop with Delete Cropped Pixels off now turns the Background into a
normal layer named "Layer 0", as in Photoshop, within the crop's one
history step: straight, extending and turned crops, and crops with a
target W x H x Resolution. The pixels past the canvas stay on every
layer, and the area an extending crop adds is transparent on every
layer instead of taking the background colour. A turned crop converts
the Background before the turn, so it turns like the other layers and
keeps its overhang.

Delete Cropped Pixels on is unchanged. Image > Reveal All keeps its
current result (the Background stays, its extension takes the
background colour) by calling the inner crop with a keep-Background
flag. Content-Aware crop fill with Delete off was not measured and is
left as it is.

Adds crates/engine/tests/it/crop_delete_off_background.rs. The #7086
test now locks the cropped layer back into a Background, the state
documents saved before this change still hold.
---
 crates/engine/src/cmd/extra_cmds.rs           |   5 +-
 crates/engine/src/cmd/image_cmds.rs           |  41 +++-
 crates/engine/src/cmd/image_cmds/tests.rs     |  11 +
 .../tests/it/crop_delete_off_background.rs    | 191 ++++++++++++++++++
 crates/engine/tests/it/main.rs                |   1 +
 crates/ui-egui/tests/it/crop_beyond_canvas.rs |   3 +-
 6 files changed, 245 insertions(+), 7 deletions(-)
 create mode 100644 crates/engine/tests/it/crop_delete_off_background.rs

diff --git a/crates/engine/src/cmd/extra_cmds.rs b/crates/engine/src/cmd/extra_cmds.rs
index 45fec91db1..f83d93bc00 100644
--- a/crates/engine/src/cmd/extra_cmds.rs
+++ b/crates/engine/src/cmd/extra_cmds.rs
@@ -877,9 +877,10 @@ pub fn specs() -> Vec<CommandSpec> {
             if all == d.doc.bounds() {
                 return Ok(json!({"changed": false}));
             }
-            // One History step named as in Photoshop, not the crop's "Crop".
+            // One History step named as in Photoshop, not the crop's "Crop". The Background stays a
+            // Background, unlike a Crop tool crop with Delete Cropped Pixels off (#10867).
             let p = json!({"x": all.x0, "y": all.y0, "width": all.width(), "height": all.height(), "deleteCroppedPixels": false});
-            crate::analysis_cmds::compound(s, "Reveal All", |s| s.execute("image.crop", p))?;
+            crate::analysis_cmds::compound(s, "Reveal All", |s| crate::image_cmds::crop_keeping_background(s, &p))?;
             Ok(json!({"changed": true}))
         }),
         spec!(
diff --git a/crates/engine/src/cmd/image_cmds.rs b/crates/engine/src/cmd/image_cmds.rs
index c8c3e0b7d2..f87fb91709 100644
--- a/crates/engine/src/cmd/image_cmds.rs
+++ b/crates/engine/src/cmd/image_cmds.rs
@@ -571,6 +571,26 @@ const MAX_CROP_SIDE: i32 = 300_000;
 
 /// Image → Crop (to the selection bounds).
 fn crop(s: &mut Session, p: &Value) -> Result<Value> {
+    crop_with(s, p, false)
+}
+
+/// Image › Reveal All's crop: as `image.crop` with Delete Cropped Pixels off, but the Background
+/// stays a Background and an extension takes the background colour (Reveal All keeps its own
+/// behaviour; only the Crop tool's was measured, #10867).
+pub(crate) fn crop_keeping_background(s: &mut Session, p: &Value) -> Result<Value> {
+    crop_with(s, p, true)
+}
+
+/// A Delete Cropped Pixels off crop turns the Background into a normal layer ("Layer 0", as Layer ›
+/// New › Layer from Background names it), as in Photoshop: it keeps the pixels past the canvas,
+/// and an extension is transparent on every layer (#10867).
+fn unlock_background_for_crop(doc: &mut Document) {
+    if let Some(bg) = doc.background_mut() {
+        crate::extra_cmds::unlock_background(bg);
+    }
+}
+
+fn crop_with(s: &mut Session, p: &Value, keep_background: bool) -> Result<Value> {
     let delete = p.get("deleteCroppedPixels").and_then(Value::as_bool).unwrap_or(true);
     // The Crop tool's Fill: Content-Aware Fill of what the crop uncovers (#3823).
     let content_aware = match p.get("contentAware") {
@@ -578,6 +598,8 @@ fn crop(s: &mut Session, p: &Value) -> Result<Value> {
         Some(Value::Bool(b)) => *b,
         Some(v) => return Err(bad("image.crop", format!("`contentAware` must be true or false, not {v}"))),
     };
+    // Content-Aware Fill with Delete off wasn't measured: it keeps filling the Background (#10867).
+    let unlock = !delete && !content_aware && !keep_background;
     // Values beyond i32 would wrap through the narrowing casts into a rectangle unrelated to
     // the numbers passed; reject them (see `commands::int_i32`).
     let explicit = match (
@@ -609,7 +631,7 @@ fn crop(s: &mut Session, p: &Value) -> Result<Value> {
     }
     if let Some(a) = crop_angle(p)? {
         let rect = explicit.ok_or_else(|| bad("image.crop", "an `angle` needs an explicit `x`, `y`, `width` and `height`"))?;
-        return rotated_crop(s, rect, a, delete, content_aware, &target);
+        return rotated_crop(s, rect, a, delete, content_aware, unlock, &target);
     }
     // An explicit rectangle (the Crop tool) may extend past the canvas; a selection crop is clamped.
     let r = explicit
@@ -622,6 +644,9 @@ fn crop(s: &mut Session, p: &Value) -> Result<Value> {
     let extension = s.tools.background;
     s.edit("Crop", |doc, active| {
         let original = doc.size;
+        if unlock {
+            unlock_background_for_crop(doc);
+        }
         crop_doc(doc, "image.crop", r, delete, extension)?;
         // A straight crop fills all of the area past the old canvas, pixels an earlier Delete Cropped
         // Pixels off crop hid there included, as Photoshop does; only a turned frame keeps them (#8060).
@@ -753,8 +778,10 @@ fn crop_angle(p: &Value) -> Result<Option<f64>> {
 /// background colour, other layers keep transparency there and every pixel of theirs), which makes
 /// the frame upright, then cropped to it (`deleteCroppedPixels` as for an unrotated crop), all in
 /// one undo step. With `content_aware`, the corners the rotation uncovers (and any area past the
-/// rotated image) are then filled from their surroundings, in the same step (#3823).
-fn rotated_crop(s: &mut Session, r: Rect, angle: f64, delete: bool, content_aware: bool, crop_target: &CropTarget) -> Result<Value> {
+/// rotated image) are then filled from their surroundings, in the same step (#3823). With `unlock`
+/// the Background becomes a normal layer before the turn, so it turns like the others, keeping its
+/// overhang and leaving the uncovered corners transparent (#10867).
+fn rotated_crop(s: &mut Session, r: Rect, angle: f64, delete: bool, content_aware: bool, unlock: bool, crop_target: &CropTarget) -> Result<Value> {
     const CMD: &str = "image.crop";
     let size = s.active().ok_or(EngineError::NoDocument)?.doc.size;
     let (w, h) = (f64::from(r.width()), f64::from(r.height()));
@@ -817,6 +844,12 @@ fn rotated_crop(s: &mut Session, r: Rect, angle: f64, delete: bool, content_awar
                 Ok(())
             })?;
         }
+        if unlock {
+            s.edit("Crop", |doc, _| {
+                unlock_background_for_crop(doc);
+                Ok(())
+            })?;
+        }
         crate::mode_cmds::rotate_arbitrary(s, &json!({"angle": angle, "direction": "ccw"}))?;
         // Color Sampler points follow the crop's origin shift too (the rotation moved them above).
         s.set_sampler_map(crop_target.sampler_map(target));
@@ -999,7 +1032,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "image.crop",
             "Crop",
             ["Image"],
-            r##"{"x":px,"y":px,"width":px,"height":px,"angle":-3600..3600=0,"deleteCroppedPixels":bool=true,"contentAware":bool=false,"targetWidth":px,"targetHeight":px,"resolution":ppi,"resample":"bicubic|bilinear|nearest|lanczos|preserveDetails"="bicubic"} → {x,y,width,height,documentWidth,documentHeight,resolution} (targetWidth/targetHeight, both or neither: the cropped area is resampled to exactly that size, as Image Size, in the same undo step; resolution: the document's new ppi; contentAware: the Crop tool's Fill › Content-Aware Fill, the area a rotated or extending crop uncovers filled from its surroundings on the Background, else the active pixel layer)"##,
+            r##"{"x":px,"y":px,"width":px,"height":px,"angle":-3600..3600=0,"deleteCroppedPixels":bool=true,"contentAware":bool=false,"targetWidth":px,"targetHeight":px,"resolution":ppi,"resample":"bicubic|bilinear|nearest|lanczos|preserveDetails"="bicubic"} → {x,y,width,height,documentWidth,documentHeight,resolution} (targetWidth/targetHeight, both or neither: the cropped area is resampled to exactly that size, as Image Size, in the same undo step; resolution: the document's new ppi; deleteCroppedPixels false: the pixels past the frame are kept and the Background becomes a normal layer, "Layer 0", so an extension is transparent on every layer; contentAware: the Crop tool's Fill › Content-Aware Fill, the area a rotated or extending crop uncovers filled from its surroundings on the Background, else the active pixel layer)"##,
             has_doc,
             crop
         ),
diff --git a/crates/engine/src/cmd/image_cmds/tests.rs b/crates/engine/src/cmd/image_cmds/tests.rs
index 64c3e5028f..fc4ce0bcf9 100644
--- a/crates/engine/src/cmd/image_cmds/tests.rs
+++ b/crates/engine/src/cmd/image_cmds/tests.rs
@@ -486,6 +486,17 @@ fn extending_the_canvas_keeps_the_backgrounds_hidden_pixels() {
             })
             .unwrap();
             s.execute("image.crop", json!({"x": 50, "y": 0, "width": 50, "height": 100, "deleteCroppedPixels": false})).unwrap();
+            // That crop makes the Background "Layer 0" now (#10867); a Background with pixels past
+            // the canvas is still in documents saved before, so lock it back into one.
+            s.edit("relock", |doc, _| {
+                let l = doc.layers.first_mut().unwrap();
+                l.name = "Background".into();
+                l.locks.transparency = true;
+                l.locks.position = true;
+                Ok(())
+            })
+            .unwrap();
+            assert!(doc(s).background().is_some());
             s.tools.background = [0.0, 0.0, 0.0, 1.0];
         };
         let mut s = Session::new();
diff --git a/crates/engine/tests/it/crop_delete_off_background.rs b/crates/engine/tests/it/crop_delete_off_background.rs
new file mode 100644
index 0000000000..bccb37e136
--- /dev/null
+++ b/crates/engine/tests/it/crop_delete_off_background.rs
@@ -0,0 +1,191 @@
+//! Crop with Delete Cropped Pixels off turns the Background into a normal layer, "Layer 0", as
+//! Photoshop does: it keeps the pixels past the canvas, and an extension is transparent on every
+//! layer. Delete on keeps the Background, and Image › Reveal All is unchanged (#10867).
+
+use photocraft_engine::Session;
+use photocraft_geom::Rect;
+use serde_json::{Value, json};
+
+const MAGENTA: [f32; 4] = [1.0, 0.0, 1.0, 1.0];
+const WHITE: [f32; 4] = [1.0, 1.0, 1.0, 1.0];
+const RED: [f32; 4] = [1.0, 0.0, 0.0, 1.0];
+
+/// The issue's test document at a tenth of the size: 80 × 50 px, a white Background and a pixel
+/// layer "Quads" covering the canvas in red, with magenta as the background colour.
+fn doc() -> Session {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 80, "height": 50, "background": "white"})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Quads"})).unwrap();
+    s.execute("tools.setColors", json!({"foreground": "#ff0000", "background": "#ff00ff"})).unwrap();
+    s.execute("select.all", json!({})).unwrap();
+    s.execute("edit.fill", json!({"contents": "foreground"})).unwrap();
+    s.execute("select.deselect", json!({})).unwrap();
+    s
+}
+
+fn d(s: &Session) -> &photocraft_doc::Document {
+    &s.active().unwrap().doc
+}
+
+fn size(s: &Session) -> (u32, u32) {
+    (d(s).size.width, d(s).size.height)
+}
+
+fn past(s: &Session) -> usize {
+    s.active().unwrap().history.past_len()
+}
+
+fn bottom(s: &Session) -> &photocraft_doc::Layer {
+    &d(s).layers[0]
+}
+
+fn content(s: &Session, i: usize) -> Rect {
+    d(s).layers[i].surface().unwrap().content_bounds()
+}
+
+/// The bottom layer is no longer a Background: a normal, unlocked layer named "Layer 0".
+fn assert_layer_0(s: &Session, what: &str) {
+    assert!(d(s).background().is_none(), "{what}: no Background left");
+    let l = bottom(s);
+    assert_eq!(l.name, "Layer 0", "{what}");
+    assert!(!l.locks.transparency && !l.locks.position, "{what}: unlocked");
+}
+
+fn crop(s: &mut Session, mut p: Value, delete: bool) {
+    p["deleteCroppedPixels"] = json!(delete);
+    let before = past(s);
+    s.execute("image.crop", p).unwrap();
+    assert_eq!(past(s), before + 1, "one undo step");
+}
+
+#[test]
+fn shrinking_turns_the_background_into_layer_0_keeping_the_hidden_pixels() {
+    let mut s = doc();
+    crop(&mut s, json!({"x": 0, "y": 0, "width": 70, "height": 50}), false);
+    assert_eq!(size(&s), (70, 50));
+    assert_layer_0(&s, "shrink");
+    // Both layers keep their 80 px, hidden past the canvas.
+    assert_eq!(content(&s, 0), Rect::new(0, 0, 80, 50), "Layer 0");
+    assert_eq!(content(&s, 1), Rect::new(0, 0, 80, 50), "Quads");
+    assert_eq!(bottom(&s).surface().unwrap().rgba(75, 25), WHITE);
+}
+
+#[test]
+fn extending_leaves_the_new_area_transparent_on_every_layer() {
+    let mut s = doc();
+    crop(&mut s, json!({"x": 0, "y": 0, "width": 90, "height": 50}), false);
+    assert_eq!(size(&s), (90, 50));
+    assert_layer_0(&s, "extend");
+    for i in 0..2 {
+        let surf = d(&s).layers[i].surface().unwrap();
+        assert_eq!(surf.rgba(85, 25)[3], 0.0, "layer {i}: the added strip is transparent");
+    }
+    assert_eq!(bottom(&s).surface().unwrap().rgba(40, 25), WHITE);
+    assert_eq!(d(&s).layers[1].surface().unwrap().rgba(40, 25), RED);
+}
+
+#[test]
+fn a_turned_crop_turns_layer_0_with_the_others() {
+    // The issue's 6.3° frame (687 × 429 of 800 × 500), centred.
+    let mut s = doc();
+    crop(&mut s, json!({"x": 6, "y": 4, "width": 68, "height": 42, "angle": 6.3}), false);
+    assert_eq!(size(&s), (68, 42));
+    assert_layer_0(&s, "turned");
+    // Every layer turned, keeping its overhang past the canvas.
+    let canvas = Rect::new(0, 0, 68, 42);
+    for i in 0..2 {
+        let c = content(&s, i);
+        assert!(c.x0 < canvas.x0 && c.y0 < canvas.y0 && c.x1 > canvas.x1 && c.y1 > canvas.y1, "layer {i} keeps its overhang: {c:?}");
+    }
+    // The corners the turn uncovered are transparent, not the background colour.
+    let surf = bottom(&s).surface().unwrap();
+    let c = content(&s, 0);
+    assert_eq!(surf.rgba(c.x0, c.y0)[3], 0.0, "an uncovered corner of Layer 0");
+    assert_eq!(surf.rgba(34, 21), WHITE);
+}
+
+#[test]
+fn the_action_steps_turned_crop_unlocks_the_background() {
+    // The action step `Crop` with `Dlt` false, rect (100,100)–(700,400) and angle 10°, scaled down.
+    let mut s = doc();
+    crop(&mut s, json!({"x": 10, "y": 10, "width": 60, "height": 30, "angle": 10}), false);
+    assert_eq!(size(&s), (60, 30));
+    assert_layer_0(&s, "action step");
+}
+
+#[test]
+fn a_target_size_crop_unlocks_the_background() {
+    let mut s = doc();
+    crop(&mut s, json!({"x": 0, "y": 0, "width": 40, "height": 50, "targetWidth": 20, "targetHeight": 25, "resolution": 150}), false);
+    assert_eq!(size(&s), (20, 25));
+    assert_layer_0(&s, "W x H x Resolution");
+}
+
+#[test]
+fn delete_on_keeps_the_background_and_fills_an_extension() {
+    for (frame, want) in [
+        (json!({"x": 0, "y": 0, "width": 70, "height": 50}), (70, 50)),
+        (json!({"x": 0, "y": 0, "width": 90, "height": 50}), (90, 50)),
+        (json!({"x": 6, "y": 4, "width": 68, "height": 42, "angle": 6.3}), (68, 42)),
+    ] {
+        let mut s = doc();
+        crop(&mut s, frame.clone(), true);
+        assert_eq!(size(&s), want, "{frame}");
+        let bg = d(&s).background().unwrap_or_else(|| panic!("{frame}: the Background stays"));
+        assert_eq!(bg.name, "Background", "{frame}");
+    }
+    let mut s = doc();
+    crop(&mut s, json!({"x": 0, "y": 0, "width": 90, "height": 50}), true);
+    assert_eq!(bottom(&s).surface().unwrap().rgba(85, 25), MAGENTA, "the extension takes the background colour");
+}
+
+#[test]
+fn undo_restores_the_background() {
+    for frame in [json!({"x": 0, "y": 0, "width": 90, "height": 50}), json!({"x": 6, "y": 4, "width": 68, "height": 42, "angle": 6.3})] {
+        let mut s = doc();
+        let before = bottom(&s).clone();
+        crop(&mut s, frame.clone(), false);
+        assert_layer_0(&s, "cropped");
+        s.execute("edit.undo", json!({})).unwrap();
+        assert_eq!(size(&s), (80, 50), "{frame}");
+        let bg = d(&s).background().unwrap_or_else(|| panic!("{frame}: undo restores the Background"));
+        assert_eq!(bg.id, before.id, "{frame}");
+        assert_eq!(bg.name, "Background", "{frame}");
+        assert!(bg.locks.transparency && bg.locks.position, "{frame}");
+        let (a, b) = (bg.surface().unwrap(), before.surface().unwrap());
+        let r = Rect::new(0, 0, 80, 50);
+        assert_eq!(a.read_region(r), b.read_region(r), "{frame}: the pixels");
+        s.execute("edit.redo", json!({})).unwrap();
+        assert_layer_0(&s, "redo");
+    }
+}
+
+#[test]
+fn reveal_all_keeps_the_background() {
+    let mut s = doc();
+    // Quads reaches 10 px past the right edge.
+    s.edit("paint past the canvas", |doc, _| {
+        let quads = doc.layers.last_mut().unwrap();
+        quads.surface_mut().unwrap().fill_rect(Rect::new(80, 0, 90, 50), &RED);
+        Ok(())
+    })
+    .unwrap();
+    let before = past(&s);
+    s.execute("image.revealAll", json!({})).unwrap();
+    assert_eq!(past(&s), before + 1);
+    assert_eq!(size(&s), (90, 50));
+    let bg = d(&s).background().expect("Reveal All keeps the Background");
+    assert_eq!(bg.name, "Background");
+    assert_eq!(bg.surface().unwrap().rgba(85, 25), MAGENTA, "the extension takes the background colour, as before");
+}
+
+#[test]
+fn a_document_without_a_background_has_nothing_to_convert() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 80, "height": 50, "background": "transparent"})).unwrap();
+    let names: Vec<String> = d(&s).layers.iter().map(|l| l.name.clone()).collect();
+    crop(&mut s, json!({"x": 0, "y": 0, "width": 90, "height": 50}), false);
+    assert_eq!(size(&s), (90, 50));
+    assert!(d(&s).background().is_none());
+    assert_eq!(d(&s).layers.iter().map(|l| l.name.clone()).collect::<Vec<_>>(), names, "no layer renamed");
+}
diff --git a/crates/engine/tests/it/main.rs b/crates/engine/tests/it/main.rs
index f6a8360a4f..862667bc5d 100644
--- a/crates/engine/tests/it/main.rs
+++ b/crates/engine/tests/it/main.rs
@@ -18,6 +18,7 @@ mod convert_keeps_references;
 mod copy_shape_placement;
 mod corpus_atn;
 mod crop_content_aware;
+mod crop_delete_off_background;
 mod current_affinity_artboards;
 mod duplicate_layer_comps;
 mod duplicate_slices;
diff --git a/crates/ui-egui/tests/it/crop_beyond_canvas.rs b/crates/ui-egui/tests/it/crop_beyond_canvas.rs
index fd23d7f888..d03ed92d0d 100644
--- a/crates/ui-egui/tests/it/crop_beyond_canvas.rs
+++ b/crates/ui-egui/tests/it/crop_beyond_canvas.rs
@@ -110,7 +110,8 @@ fn editing_a_crop_frame_shows_the_pixels_past_the_canvas() {
         let app = h.state_mut();
         // 300 × 120: red down the left 60 px and blue down the right 60 px of a new layer, then
         // cropped to (50, 0) 200 × 100 keeping the pixels: 50 px of red past the left edge, 50 of
-        // blue past the right, and 20 rows of the white Background below.
+        // blue past the right, and 20 rows of the white Background below (the crop makes it "Layer 0",
+        // which keeps them, #10867).
         app.run("file.new", json!({"width": 300, "height": 120, "background": "white"})).expect("new");
         app.run("layer.new.layer", json!({})).expect("layer");
         for (x, color) in [(0, "#ff0000"), (240, "#0000ff")] {

From 50360ac4eff6ce7daa0d7a1ff0c16c86ee803424 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 11:30:37 -0600
Subject: [PATCH 058/109] Record portable nudges, document switches, and type
 positions

---
 crates/engine/src/actions_record.rs         | 23 ++++++-
 crates/engine/src/cmd.rs                    |  2 +-
 crates/engine/src/cmd/actions_cmds.rs       | 66 ++++++++++++++++++++-
 crates/engine/src/cmd/actions_cmds/tests.rs | 58 ++++++++++++++++++
 crates/engine/src/jobs.rs                   |  2 +-
 crates/engine/src/session/documents.rs      |  7 +++
 crates/ui-egui/src/canvas/tabs_tests.rs     | 11 ++++
 crates/ui-egui/src/menus/invoke.rs          |  4 +-
 docs/gaps.md                                | 11 ++--
 docs/scorecard.md                           |  2 +-
 docs/target-app-parity.md                   |  5 +-
 scorecard/automation.toml                   |  2 +-
 12 files changed, 180 insertions(+), 13 deletions(-)

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
index 6745f40321..82781750b2 100644
--- a/crates/engine/src/actions_record.rs
+++ b/crates/engine/src/actions_record.rs
@@ -46,8 +46,29 @@ pub(crate) fn needs_source_layer(id: &str) -> bool {
 }
 
 /// `params` with its `layer` id made portable (see the module doc).
-pub(crate) fn portable(id: &str, mut params: Value, before: &Before) -> Value {
+pub(crate) fn portable(s: &Session, id: &str, mut params: Value, before: &Before) -> Value {
+    if id == "document.activate"
+        && let (Some(from), Some(to)) = (before.doc.as_ref().map(|doc| doc.id), s.active().map(|state| state.doc.id))
+        && let Some(offset) = s.document_offset_between(from, to)
+    {
+        return serde_json::json!({"offset": offset});
+    }
     let Some(doc) = before.doc.as_deref() else { return params };
+    if id == "type.create" && s.actions.recording.is_some() && params.get("box").is_none() && doc.size.width > 0 && doc.size.height > 0 {
+        let x = params.get("x").and_then(Value::as_f64).unwrap_or(0.0);
+        let y = params.get("y").and_then(Value::as_f64).unwrap_or(0.0);
+        let x_percent = x / f64::from(doc.size.width) * 100.0;
+        let y_percent = y / f64::from(doc.size.height) * 100.0;
+        if x_percent.is_finite()
+            && y_percent.is_finite()
+            && let Some(object) = params.as_object_mut()
+        {
+            object.remove("x");
+            object.remove("y");
+            object.insert("xPercent".into(), serde_json::json!(x_percent));
+            object.insert("yPercent".into(), serde_json::json!(y_percent));
+        }
+    }
     let Some(target) = params.get("layer").and_then(Value::as_u64).map(LayerId) else { return params };
     let Some(obj) = params.as_object_mut() else { return params };
     let only_selected = before.selected.len() <= 1;
diff --git a/crates/engine/src/cmd.rs b/crates/engine/src/cmd.rs
index 19e1e94afc..0f9fa19a80 100644
--- a/crates/engine/src/cmd.rs
+++ b/crates/engine/src/cmd.rs
@@ -1066,7 +1066,7 @@ fn build() -> Vec<CommandSpec> {
                 };
                 if s.set_active(idx) { Ok(json!({"document": idx})) } else { Err(EngineError::Other(format!("no document at index {idx}"))) }
             },
-            journal: false,
+            journal: true,
         },
         CommandSpec {
             id: "document.move",
diff --git a/crates/engine/src/cmd/actions_cmds.rs b/crates/engine/src/cmd/actions_cmds.rs
index ea68d86b50..c321129fb4 100644
--- a/crates/engine/src/cmd/actions_cmds.rs
+++ b/crates/engine/src/cmd/actions_cmds.rs
@@ -140,6 +140,23 @@ pub(crate) fn recorded_params(s: &Session, id: &str, mut p: Value) -> Value {
 /// Resolve the recorded visibility target identically in engine and shell playback.
 pub fn playback_params(s: &Session, id: &str, p: &Value) -> Result<Value> {
     let mut p = p.clone();
+    if id == "type.create" && (p.get("xPercent").is_some() || p.get("yPercent").is_some()) {
+        if p.get("box").is_some() || p.get("x").is_some() || p.get("y").is_some() {
+            return Err(bad(id, "recorded type position cannot mix percentages with pixel coordinates or a box"));
+        }
+        let size = s.active().ok_or(EngineError::NoDocument)?.doc.size;
+        for (percent_key, pixel_key, dimension) in [("xPercent", "x", size.width), ("yPercent", "y", size.height)] {
+            let percent = p.get(percent_key).and_then(Value::as_f64).ok_or_else(|| bad(id, format!("invalid `{percent_key}`")))?;
+            let pixel = percent / 100.0 * f64::from(dimension);
+            if !pixel.is_finite() || pixel.abs() > f64::from(f32::MAX) {
+                return Err(bad(id, format!("`{percent_key}` is outside the canvas coordinate range")));
+            }
+            if let Some(object) = p.as_object_mut() {
+                object.remove(percent_key);
+                object.insert(pixel_key.into(), json!(pixel));
+            }
+        }
+    }
     if id == "layer.setProps"
         && let Some(target) = p.get("_actionLayer")
     {
@@ -401,7 +418,7 @@ pub(crate) fn flush_recording(s: &mut Session) -> Result<()> {
     if idx >= s.actions.list.len() {
         return Err(bad("actions.stop", "the action being recorded no longer exists"));
     }
-    let steps: Vec<_> = pending_steps(s, idx).cloned().collect();
+    let steps = fold_recorded_nudges(pending_steps(s, idx).cloned());
     s.actions.recording = Some((s.journal.len(), idx));
     if !steps.is_empty() {
         s.actions.list[idx].steps.extend(steps);
@@ -410,6 +427,53 @@ pub(crate) fn flush_recording(s: &mut Session) -> Result<()> {
     Ok(())
 }
 
+/// Consecutive Move-tool keystrokes in one UI nudge run are one relative action step.
+/// The UI's `coalesce` run id distinguishes a held key from a later, separate gesture.
+fn fold_recorded_nudges(steps: impl IntoIterator<Item = (String, Value)>) -> Vec<(String, Value)> {
+    let mut out: Vec<(String, Value)> = Vec::new();
+    let mut last_run: Option<String> = None;
+    for (id, mut params) in steps {
+        let run = (id == "layer.translate")
+            .then(|| params.as_object())
+            .flatten()
+            .filter(|p| p.keys().all(|key| matches!(key.as_str(), "dx" | "dy" | "coalesce")))
+            .and_then(|p| p.get("coalesce").and_then(Value::as_str).filter(|run| run.starts_with("nudge:")))
+            .map(str::to_string);
+        if let Some(run) = &run {
+            let dx = params.get("dx").and_then(Value::as_f64);
+            let dy = params.get("dy").and_then(Value::as_f64);
+            if let (Some(dx), Some(dy)) = (dx, dy)
+                && dx.is_finite()
+                && dy.is_finite()
+            {
+                if last_run.as_ref() == Some(run)
+                    && let Some((last_id, previous)) = out.last_mut()
+                    && last_id == &id
+                {
+                    let sum_x = previous.get("dx").and_then(Value::as_f64).unwrap_or(0.0) + dx;
+                    let sum_y = previous.get("dy").and_then(Value::as_f64).unwrap_or(0.0) + dy;
+                    if sum_x.is_finite() && sum_y.is_finite() {
+                        previous["dx"] = json!(sum_x);
+                        previous["dy"] = json!(sum_y);
+                        continue;
+                    }
+                }
+                if let Some(object) = params.as_object_mut() {
+                    object.remove("coalesce");
+                    object.insert("dx".into(), json!(dx));
+                    object.insert("dy".into(), json!(dy));
+                }
+                last_run = Some(run.clone());
+                out.push((id, params));
+                continue;
+            }
+        }
+        last_run = None;
+        out.push((id, params));
+    }
+    out
+}
+
 fn stop(s: &mut Session, _p: &Value) -> Result<Value> {
     not_playing(s, "actions.stop")?;
     let Some((_, idx)) = s.actions.recording else {
diff --git a/crates/engine/src/cmd/actions_cmds/tests.rs b/crates/engine/src/cmd/actions_cmds/tests.rs
index 1eef6d4b34..e632e194da 100644
--- a/crates/engine/src/cmd/actions_cmds/tests.rs
+++ b/crates/engine/src/cmd/actions_cmds/tests.rs
@@ -339,6 +339,64 @@ fn record_explicit_transform_keeps_one_replayable_step() {
     assert_eq!(pixel(&s, 0, 12, 2), vec![0.0; 4]);
 }
 
+#[test]
+fn recording_folds_one_run_of_move_tool_nudges() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 24, "height": 24, "background": "transparent"})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Target"})).unwrap();
+    s.execute("actions.record", json!({"name": "Nudge"})).unwrap();
+    for (dx, dy, run) in [(1, 0, "nudge:1"), (1, 0, "nudge:1"), (1, 10, "nudge:1"), (0, 1, "nudge:2")] {
+        s.execute("layer.translate", json!({"dx": dx, "dy": dy, "coalesce": run})).unwrap();
+    }
+    s.execute("actions.stop", json!({})).unwrap();
+    let steps = &s.actions.list[0].steps;
+    assert_eq!(steps, &[("layer.translate".into(), json!({"dx": 3.0, "dy": 10.0})), ("layer.translate".into(), json!({"dx": 0.0, "dy": 1.0}))]);
+}
+
+#[test]
+fn recording_document_activation_uses_opening_order_offset() {
+    let mut s = Session::new();
+    for name in ["First", "Second"] {
+        s.execute("file.new", json!({"width": 8, "height": 8, "name": name})).unwrap();
+    }
+    s.execute("actions.record", json!({"name": "Switch"})).unwrap();
+    s.execute("document.activate", json!({"document": 0})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    assert_eq!(s.actions.list[0].steps, [("document.activate".into(), json!({"offset": -1}))]);
+}
+
+#[test]
+fn recorded_point_text_position_scales_with_the_playback_canvas() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 100, "height": 100, "background": "transparent"})).unwrap();
+    s.execute("actions.record", json!({"name": "Caption"})).unwrap();
+    s.execute("type.create", json!({"x": 20, "y": 30, "text": "Hi", "size": 12})).unwrap();
+    s.execute("actions.stop", json!({})).unwrap();
+    assert_eq!(s.actions.list[0].steps[0].1["xPercent"], json!(20.0));
+    assert_eq!(s.actions.list[0].steps[0].1["yPercent"], json!(30.0));
+    s.execute("file.new", json!({"width": 200, "height": 300, "background": "transparent"})).unwrap();
+    let played = s.execute("actions.play", json!({"action": "Caption"})).unwrap();
+    assert!(played.get("failed").is_none(), "{played}");
+    let info = s.execute("type.info", json!({})).unwrap();
+    assert_eq!(info["transform"][4], json!(40.0));
+    assert_eq!(info["transform"][5], json!(90.0));
+}
+
+#[test]
+fn recorded_point_text_rejects_invalid_relative_positions() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 100, "height": 100})).unwrap();
+    for params in [
+        json!({"xPercent": 20}),
+        json!({"xPercent": "20", "yPercent": 30}),
+        json!({"xPercent": 20, "yPercent": 30, "x": 20}),
+        json!({"xPercent": 20, "yPercent": 30, "box": [0, 0, 10, 10]}),
+        json!({"xPercent": 1e100, "yPercent": 30}),
+    ] {
+        assert!(playback_params(&s, "type.create", &params).is_err(), "{params}");
+    }
+}
+
 #[test]
 fn recorded_single_layer_transform_replays_after_layer_ids_shift() {
     let mut s = Session::new();
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index fc5fd359b0..eb848b2ac6 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -979,7 +979,7 @@ impl Session {
             _ => crate::layer_multi_cmds::recorded_step(self, id, params, pre_selected),
         };
         let params = crate::actions_cmds::recorded_params(self, id, params);
-        let params = crate::actions_record::portable(id, params, before);
+        let params = crate::actions_record::portable(self, id, params, before);
         match crate::actions_record::fold_keystroke(self, id, &params, self.typed_layer) {
             crate::actions_record::Keystroke::Folded => {}
             crate::actions_record::Keystroke::None => {
diff --git a/crates/engine/src/session/documents.rs b/crates/engine/src/session/documents.rs
index a82f6c18e6..f47c1befa2 100644
--- a/crates/engine/src/session/documents.rs
+++ b/crates/engine/src/session/documents.rs
@@ -114,6 +114,13 @@ impl Session {
         self.docs.iter().position(|st| st.doc.id == *id).ok_or(EngineError::NoDocument)
     }
 
+    /// Relative opening-order distance between two open documents, for portable action steps.
+    pub(crate) fn document_offset_between(&self, from: photocraft_doc::DocId, to: photocraft_doc::DocId) -> Option<i64> {
+        let from = self.open_document_order.iter().position(|&id| id == from)?;
+        let to = self.open_document_order.iter().position(|&id| id == to)?;
+        i64::try_from(to).ok()?.checked_sub(i64::try_from(from).ok()?)
+    }
+
     /// Add a document (from File → New, an import, etc.) and make it active.
     /// Preserve its identity unless another open document already owns it.
     /// Identity-dependent callers must read the admitted document at the returned index.
diff --git a/crates/ui-egui/src/canvas/tabs_tests.rs b/crates/ui-egui/src/canvas/tabs_tests.rs
index 677949600b..6285b7e651 100644
--- a/crates/ui-egui/src/canvas/tabs_tests.rs
+++ b/crates/ui-egui/src/canvas/tabs_tests.rs
@@ -150,6 +150,17 @@ fn ctrl_tab_cycles_through_the_document_tabs() {
     assert!(!h.state().ui.panels.dock, "plain Tab hides the panels");
 }
 
+#[test]
+fn ctrl_tab_records_a_relative_document_switch() {
+    let mut h = harness(2, ThemeKind::Pro);
+    h.state_mut().run("actions.record", json!({"name": "Switch"})).unwrap();
+    h.key_press_modifiers(ctrl(), egui::Key::Tab);
+    h.run_steps(2);
+    h.state_mut().run("actions.stop", json!({})).unwrap();
+    let steps = &h.state().session.actions.list[0].steps;
+    assert_eq!(steps, &[("document.activate".into(), json!({"offset": -1}))]);
+}
+
 /// One document: Ctrl+Tab stays on it quietly; a focused widget or text field doesn't keep the key.
 #[test]
 fn ctrl_tab_with_one_document_or_a_focused_field() {
diff --git a/crates/ui-egui/src/menus/invoke.rs b/crates/ui-egui/src/menus/invoke.rs
index b8d4791d80..a089803be8 100644
--- a/crates/ui-egui/src/menus/invoke.rs
+++ b/crates/ui-egui/src/menus/invoke.rs
@@ -707,7 +707,9 @@ fn invoke_window_command(app: &mut PhotocraftApp, ctx: &egui::Context, id: &str)
             let count = app.session.documents().len();
             let active = app.session.active_index().ok_or("no document open")?;
             let next = if id == "window.nextDocument" { (active + 1) % count } else { (active + count - 1) % count };
-            app.session.set_active(next);
+            if next != active {
+                app.run("document.activate", json!({"document": next}))?;
+            }
             app.jobs.focus = None;
             Ok(json!({"document": next}))
         })()),
diff --git a/docs/gaps.md b/docs/gaps.md
index f532a6ed07..b2a733c500 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -1,6 +1,6 @@
 # Where PhotoCraft falls short of Photoshop
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-01 · **Change:** minor (G11: action recording names unique layers and folds Type keystrokes, #4514; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-02 · **Change:** minor (G11: action recording folds Move-tool nudges, records relative keyboard document switches and scales point text placement; paragraph boxes remain open, #4514; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 Every known shortfall against Photoshop 2026 (27.11.0), one entry each, ranked by user impact
 on the way to beta. This is the work list agents pick from: take the highest-ranked entry that
@@ -122,9 +122,11 @@ what an agent can't finish alone.
 - **2026-10-13 evidence:** Batch supports [output naming templates](batch-naming.md) using
   `{name}`, `{serial}` and a captured UTC `{date}`, with a starting serial number. Colliding
   names remain errors; custom output names cannot replace inputs. AUTO-219-5 stays partial.
-- **Done 2026-11-01 (#4514):** Action recording drops an implicit active-layer id, names a
-  unique non-active layer, and folds Type keystrokes into whole-text steps (AUTO-219-1).
-  Duplicate layer names remain ambiguous and keep the id; use unique names for portable playback.
+- **Partial 2026-11-02 (#4514):** Action recording drops an implicit active-layer id, names a
+  unique non-active layer, folds Type keystrokes into whole-text steps and Move-tool nudge runs
+  into one relative move, records keyboard document switches as opening-order offsets, and
+  places recorded point text by canvas percentage. Duplicate layer names remain ambiguous and
+  keep the id; paragraph text boxes still use absolute coordinates. AUTO-219-1 remains partial.
 - **Missing:** Batch recursion, open-document inputs, progress/cancel and an error-log file
   (AUTO-219-5), ExtendScript/UXP compatibility. `.atn` steps outside the
   mapped events (paths, scripts, Generative Fill, Filter Gallery effects other than Spatter,
@@ -427,6 +429,7 @@ what an agent can't finish alone.
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | Action recording folds Move-tool nudge runs, records keyboard document switches by opening-order offset and places point text by canvas percentage; paragraph boxes remain absolute (AUTO-219-1, #4514); parity percentages unchanged |
 | 2026-11-01 | minor | Action recording stores portable layer targets and whole-text Type steps where unambiguous (AUTO-219-1, #4514); duplicate names remain ambiguous; parity percentages unchanged |
 | 2026-10-27 | minor | Smooth/Feather command reads and replacement use selection bounds plus blur reach; full-canvas reference and release comparisons extended; percentages and scorecard budgets unchanged |
 | 2026-11-01 | minor | G9: 11 of 183 preferences do nothing (was 12): Graphics Adapter (`performance.gpuAdapter`) always worked, but startup read it by raw JSON key, which the scorecard prefs audit can't see; it now reads the typed Performance section; no estimate changed |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index 503cb419fa..3d80c8f1d7 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -255,7 +255,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | Id | Target | Status | Issue | Note |
 |---|---|---|---|---|
 | AUTO-1 | Every menu item dispatches a command id (UI, CLI, control channel and MCP share them) | done |  | docs/parity-checklist.md: all menu items live; menus.rs is_live |
-| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | partial | [#219](https://github.com/storytold/photocraft/issues/219) | actions_record.rs: active layer ids are dropped, uniquely named layers replay by name, and Type tool keystrokes fold per document and layer; full coverage of all numeric-only command receivers and ambiguous layer names is still open |
+| AUTO-219-1 | Record actions in a document-independent form (implicit layer, merged type keystrokes) | partial | [#219](https://github.com/storytold/photocraft/issues/219) | actions_record.rs/actions_cmds.rs: active layer ids are dropped, uniquely named layers replay by name, Type tool keystrokes and Move-tool nudge runs fold, document activation records an opening-order offset, and point text placement scales with the playback canvas; numeric-only receivers, ambiguous layer names and paragraph box placement remain open, #4514 |
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index fb12e65997..63d730e406 100644
--- a/docs/target-app-parity.md
+++ b/docs/target-app-parity.md
@@ -1,6 +1,6 @@
 # PhotoCraft vs Adobe Photoshop: target-app parity
 
-> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-01 · **Change:** minor (Automation recording uses portable layer references and whole-text Type steps, #4514; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-02 · **Change:** minor (Automation recording folds Move-tool nudge runs, records keyboard document switches by opening-order offset and scales point text placement; paragraph boxes remain open, #4514; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 The authoritative answer to "how close is PhotoCraft to Photoshop, and how much work is left". The
 one-page summary is [`ROADMAP.md`](../ROADMAP.md); the ranked work list is [`gaps.md`](gaps.md);
@@ -176,7 +176,7 @@ parity for the area and are already contained in the dimension rows above.
 | Vector shapes and paths | 55% | 80–140 | Pen, Direct/Path Selection, shapes, shape strokes. Freeform and Curvature Pen (#1054). Add/Delete Anchor Point and Convert Point tools exist (`Tool` enum); on-canvas corner radius widgets on live rectangles (TOOL-214-12, 2026-10-13); shape Density and Feather, the path as the fill's soft vector mask, matching Photoshop's 10 px feather ramp within 1 level (#5846, 2026-10-15); missing path-point nudge; shape parity tracking issue #2496 |
 | Colour management and modes | 70% | 60–100 | Own ICC engine, soft proof, CMYK/Lab/Indexed/Duotone/Multichannel; no Adobe CMYK profiles, spot plates in PSD and TIFF only (FILE-215-17: no RGB/CMYK spot preview or PDF Separation), monitor profile only at launch |
 | Camera Raw and computational photo (Photomerge, HDR, lens) | 45% | 120–200 | Raw for DNG/CR2/NEF/ARW/RW2/ORF/RAF(uncompressed)/PEF; no CR3; ACR dialog partial (no masking; no per-camera colour for non-DNG cameras); generic lens profiles only |
-| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; recording uses implicit active layers, unique layer names and whole-text Type steps (AUTO-219-1, #4514; duplicate names remain ambiguous); Actions panel remains partial (AUTO-219-2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); compound layer properties export as separate Set events with rename last (#8304, 2026-10-21; independent Photoshop replay pending); no ExtendScript/UXP |
+| Automation, actions, batch, scripting | 45% | 120–200 | CLI/MCP/control channel ahead of Photoshop; recording uses implicit active layers, unique layer names, whole-text Type steps, bundled Move-tool nudges, relative keyboard document switches and canvas-relative point text (AUTO-219-1, #4514; duplicate names and paragraph boxes remain open); Actions panel remains partial (AUTO-219-2); `.atn` load/save since 2026-10-12 (112 events mapped, the rest kept verbatim); compound layer properties export as separate Set events with rename last (#8304, 2026-10-21; independent Photoshop replay pending); no ExtendScript/UXP |
 | File I/O | 60% | 300–500 | See [file-format-parity.md](file-format-parity.md) |
 | Print, export, Save for Web | 50% | 60–100 | JPEG Options without Matte, progressive Scans or size preview (FILE-215-19), no Photoshop PDF, no separations, Save for Web settings not remembered |
 | Video / timeline, data-driven graphics | 30% | 100–200 | Menu items live; frame model persists in `.pcraft`; no PSD video-layer mapping |
@@ -585,6 +585,7 @@ See [method, raw measurements and reproduction](five-algorithm-performance.md).
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | AUTO-219-1: action recording folds Move-tool nudges, records relative document switches and scales point text placement to the playback canvas; duplicate names and paragraph box placement remain open; Automation parity estimate unchanged |
 | 2026-11-01 | minor | AUTO-219-1: action recording uses implicit or uniquely named layers and folds Type keystrokes into whole-text steps; duplicate names remain ambiguous; Automation parity estimate unchanged |
 | 2026-11-01 | minor | UI / UX and Workspace rows: 11 of 183 preferences do nothing (was 12); Graphics Adapter always worked, but startup read it by raw JSON key, which the scorecard audit can't see. Percentages and estimates unchanged |
 | 2026-10-27 | minor | Smooth/Feather command reads and replacement use selection bounds plus blur reach; full-canvas reference and release comparisons extended; percentages and scorecard budgets unchanged |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index f5d8c09208..816284cb47 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -16,7 +16,7 @@ id = "AUTO-219-1"
 target = "Record actions in a document-independent form (implicit layer, merged type keystrokes)"
 status = "partial"
 issue = 219
-note = "actions_record.rs: active layer ids are dropped, uniquely named layers replay by name, and Type tool keystrokes fold per document and layer; full coverage of all numeric-only command receivers and ambiguous layer names is still open"
+note = "actions_record.rs/actions_cmds.rs: active layer ids are dropped, uniquely named layers replay by name, Type tool keystrokes and Move-tool nudge runs fold, document activation records an opening-order offset, and point text placement scales with the playback canvas; numeric-only receivers, ambiguous layer names and paragraph box placement remain open, #4514"
 
 [[item]]
 id = "AUTO-219-2"

From 00f75988b947f03d4d66b81d3179771e6a81f848 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 11:30:58 -0600
Subject: [PATCH 059/109] Match measured Photoshop Batch naming and error logs

---
 apps/photocraft-cli/src/batch.rs              |  20 +--
 apps/photocraft-cli/src/error.rs              |   3 -
 apps/photocraft-cli/tests/it/cli.rs           |  47 ++++---
 crates/engine/src/cmd/file_cmds.rs            |   4 +-
 .../engine/src/cmd/file_cmds/batch_naming.rs  |  39 ++++--
 crates/engine/src/cmd/file_cmds/batch_run.rs  | 115 ++++++++++++-----
 crates/engine/src/cmd/file_cmds/save.rs       |   7 ++
 crates/engine/src/cmd/file_cmds/tests.rs      | 117 +++++++++++++-----
 docs/batch-naming.md                          |  45 +++++--
 docs/gaps.md                                  |  17 +--
 docs/scorecard.md                             |   4 +-
 docs/target-app-parity.md                     |   7 +-
 scorecard/automation.toml                     |   4 +-
 13 files changed, 294 insertions(+), 135 deletions(-)

diff --git a/apps/photocraft-cli/src/batch.rs b/apps/photocraft-cli/src/batch.rs
index 354c06b58c..5becc70c31 100644
--- a/apps/photocraft-cli/src/batch.rs
+++ b/apps/photocraft-cli/src/batch.rs
@@ -76,7 +76,6 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     };
     inputs.sort_by(|a, b| a.path.cmp(&b.path));
     let (mut ok, mut failed) = (0, 0);
-    let mut written = photocraft_engine::file_cmds::OutputClaims::default();
     // `--format .jpg` names outputs `<stem>.jpg`, as `--format jpg` does (#490).
     let format = a.export.format.as_deref().map(|f| f.strip_prefix('.').unwrap_or(f));
     let named = photocraft_engine::file_cmds::plan_batch_names(
@@ -94,10 +93,12 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
                 let path = Path::new(&input.path);
                 let ext = format.map(str::to_owned).or_else(|| path.extension().map(|e| e.to_string_lossy().into_owned())).unwrap_or_else(|| "png".into());
                 let stem = path.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_default();
-                out_dir.join(&input.rel_dir).join(format!("{stem}.{ext}"))
+                out_dir.join(format!("{stem}.{ext}"))
             })
             .collect(),
     };
+    let plan: Vec<_> = inputs.iter().zip(&targets).map(|(input, target)| (input.path.clone(), target.to_string_lossy().into_owned())).collect();
+    photocraft_engine::file_cmds::validate_flat_outputs(&plan).map_err(|error| CliError::Naming(error.to_string()))?;
     if let Some(log) = &a.error_log {
         let same = |path: &Path| photocraft_engine::file_cmds::same_destination(log, path);
         if inputs.iter().any(|input| same(Path::new(&input.path))) || targets.iter().any(|target| same(target)) {
@@ -109,9 +110,7 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     for (input, target) in inputs.iter().zip(targets) {
         let input = Path::new(&input.path);
         let ext = target.extension().map(|ext| ext.to_string_lossy().into_owned()).unwrap_or_else(|| "png".into());
-        let target_text = target.to_string_lossy();
         let r = (|| -> Result<Vec<String>> {
-            written.check(&target_text).map_err(CliError::OutputClaimed)?;
             if let Some(parent) = target.parent() {
                 std::fs::create_dir_all(parent)?;
             }
@@ -139,7 +138,6 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
         match r {
             Ok(ws) => {
                 ok += 1;
-                written.record(&target_text, &input.to_string_lossy());
                 let _ = writeln!(out, "ok    {} -> {}", input.display(), target.display());
                 warn_all(err, &ws);
             }
@@ -153,15 +151,9 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
             }
         }
     }
-    if let Some(path) = &a.error_log
-        && !failures.is_empty()
-    {
-        let date = photocraft_engine::analysis_cmds::now_iso();
-        let mut body = format!("PhotoCraft Batch: {} error(s) on {}\n", failures.len(), date.get(..10).unwrap_or("unknown date"));
-        for (file, error) in &failures {
-            body.push_str(&format!("{file}: {error}\n"));
-        }
-        photocraft_format::atomic_write(path, body.as_bytes())?;
+    if let Some(path) = &a.error_log {
+        let bytes = photocraft_engine::file_cmds::encode_batch_error_log(failures.iter().map(|(file, error)| (file.as_str(), error.as_str())));
+        photocraft_format::atomic_write(path, &bytes)?;
     }
     let skipped = inputs.len().saturating_sub(ok + failed);
     if skipped > 0 {
diff --git a/apps/photocraft-cli/src/error.rs b/apps/photocraft-cli/src/error.rs
index c6c754e33f..55e8df48e2 100644
--- a/apps/photocraft-cli/src/error.rs
+++ b/apps/photocraft-cli/src/error.rs
@@ -32,9 +32,6 @@ pub(crate) enum CliError {
     OutIsInput(PathBuf),
     #[error("--out {} is the --in folder, so the results would replace the originals: choose another --out folder, or pass --in-place to overwrite them", .0.display())]
     OutIsIn(PathBuf),
-    /// Another input already wrote this output ([`photocraft_engine::file_cmds::OutputClaims::check`]).
-    #[error("{0}")]
-    OutputClaimed(String),
     #[error("--naming: {0}")]
     Naming(String),
     #[error("{0}")]
diff --git a/apps/photocraft-cli/tests/it/cli.rs b/apps/photocraft-cli/tests/it/cli.rs
index 5d7b597134..c715ced213 100644
--- a/apps/photocraft-cli/tests/it/cli.rs
+++ b/apps/photocraft-cli/tests/it/cli.rs
@@ -434,9 +434,25 @@ fn batch_applies_actions_to_directory() {
     write_png(&inp.join("two.png"), 9, 9, 2);
     std::fs::write(inp.join("notes.txt"), "ignored").unwrap();
     let actions = d.join("actions.json");
+    let log = d.join("errors.txt");
     std::fs::write(&actions, json!([{"command": "layer.new.layer", "params": {"name": "Batch"}}]).to_string()).unwrap();
-    let out = ok(bin().args(["batch", "--actions"]).arg(&actions).arg("--in").arg(&inp).arg("--out").arg(&outp).args(["--format", "pcraft"])).stdout;
+    let out = ok(bin()
+        .args(["batch", "--actions"])
+        .arg(&actions)
+        .arg("--in")
+        .arg(&inp)
+        .arg("--out")
+        .arg(&outp)
+        .args(["--format", "pcraft", "--error-log"])
+        .arg(&log))
+    .stdout;
     assert!(out.contains("2 succeeded, 0 failed"), "{out}");
+    let clean_log = std::fs::read(&log).unwrap();
+    assert!(clean_log.starts_with(&[0xff, 0xfe]));
+    let (pairs, remainder) = clean_log[2..].as_chunks::<2>();
+    assert!(remainder.is_empty());
+    let body = String::from_utf16(&pairs.iter().map(|pair| u16::from_le_bytes(*pair)).collect::<Vec<_>>()).unwrap();
+    assert_eq!(body, "Batch Start\r\n\r\nBatch End\r\n");
     for n in ["one", "two"] {
         let info = ok(bin().arg("info").arg(outp.join(format!("{n}.pcraft")))).stdout;
         let v: Value = serde_json::from_str(&info).unwrap();
@@ -470,11 +486,15 @@ fn batch_recursive_naming_stop_and_error_log() {
     let stdout = String::from_utf8_lossy(&result.stdout);
     assert!(!result.status.success(), "{stdout}");
     assert!(stdout.contains("3 succeeded, 1 failed"), "{stdout}");
-    for file in ["a-05.png", "sub/a-06.png", "sub/c-08.png"] {
+    for file in ["a-05.png", "a-06.png", "c-08.png"] {
         assert!(output.join(file).is_file(), "{file}: {stdout}");
     }
-    let errors = std::fs::read_to_string(log).unwrap();
-    assert!(errors.contains("1 error(s)") && errors.contains("b.png"), "{errors}");
+    let bytes = std::fs::read(log).unwrap();
+    assert!(bytes.starts_with(&[0xff, 0xfe]));
+    let (pairs, remainder) = bytes[2..].as_chunks::<2>();
+    assert!(remainder.is_empty());
+    let errors = String::from_utf16(&pairs.iter().map(|pair| u16::from_le_bytes(*pair)).collect::<Vec<_>>()).unwrap();
+    assert!(errors.contains("Batch Start\r\n") && errors.contains("b.png") && errors.ends_with("Batch End\r\n"), "{errors}");
 
     let stopped = root.join("stopped");
     let result = run(&stopped, &["--recursive", "--stop-on-error"]);
@@ -483,7 +503,7 @@ fn batch_recursive_naming_stop_and_error_log() {
     assert!(!result.status.success(), "{stdout}");
     assert!(stdout.contains("2 succeeded, 1 failed, 1 skipped"), "{stdout}");
     assert!(stderr.contains("--stop-on-error"), "{stderr}");
-    assert!(!stopped.join("sub/c.png").exists());
+    assert!(!stopped.join("c.png").exists());
 
     let collision = root.join("collision");
     let alias = collision.join("../collision/a.png");
@@ -1014,9 +1034,9 @@ fn mcp_bridge_takes_a_port_or_an_address() {
     let _ = child.wait();
 }
 
-/// `--format` mapping two inputs to one name fails the second instead of overwriting the first (#420).
+/// Photoshop Batch processes every input in order, replacing earlier flat results with the same name.
 #[test]
-fn batch_fails_inputs_that_share_an_output_name() {
+fn batch_later_input_replaces_a_same_named_output() {
     let d = tmp("batch-collide");
     let input = d.join("in");
     std::fs::create_dir_all(&input).unwrap();
@@ -1031,15 +1051,10 @@ fn batch_fails_inputs_that_share_an_output_name() {
     let out_dir = d.join("out");
     let o = bin().args(["batch", "--actions"]).arg(&actions).arg("--in").arg(&input).arg("--out").arg(&out_dir).args(["--format", "png"]).output().unwrap();
     let (out, err) = (String::from_utf8_lossy(&o.stdout), String::from_utf8_lossy(&o.stderr));
-    assert!(
-        !o.status.success(),
-        "a lost result must fail the run
-{out}
-{err}"
-    );
-    assert!(out.contains("1 succeeded, 2 failed"), "{out}");
-    assert_eq!(err.matches("not written").count(), 2, "{err}");
-    assert_eq!(std::fs::read_dir(&out_dir).unwrap().count(), 1);
+    assert!(o.status.success(), "{out}{err}");
+    assert!(out.contains("3 succeeded, 0 failed"), "{out}");
+    assert!(out_dir.join("a.png").is_file());
+    assert!(std::fs::read_dir(&out_dir).unwrap().count() <= 2);
     // Keeping each file's format, every input gets its own output.
     let out_dir = d.join("same");
     let out = ok(bin().args(["batch", "--actions"]).arg(&actions).arg("--in").arg(&input).arg("--out").arg(&out_dir)).stdout;
diff --git a/crates/engine/src/cmd/file_cmds.rs b/crates/engine/src/cmd/file_cmds.rs
index a9439cf2dc..58cb9c0d00 100644
--- a/crates/engine/src/cmd/file_cmds.rs
+++ b/crates/engine/src/cmd/file_cmds.rs
@@ -31,7 +31,9 @@ mod save;
 pub use batch_naming::plan as plan_batch_names;
 #[cfg(test)]
 pub(crate) use batch_run::MAX_SUBFOLDER_DEPTH;
-pub use batch_run::{BatchInput, OutputClaims, list_images_tree};
+#[cfg(not(target_arch = "wasm32"))]
+pub use batch_run::validate_flat_outputs;
+pub use batch_run::{BatchInput, OutputClaims, encode_batch_error_log, list_images_tree};
 use batch_run::{batch, same_format};
 pub(crate) use batch_run::{batch_inputs, batch_keeps_step, batch_save_point, process_files};
 pub use export::{LayerExportReport, SkippedExportLayer, bake_cube, export_layers_report_with, export_layers_with};
diff --git a/crates/engine/src/cmd/file_cmds/batch_naming.rs b/crates/engine/src/cmd/file_cmds/batch_naming.rs
index 8d6bfba083..89b5203409 100644
--- a/crates/engine/src/cmd/file_cmds/batch_naming.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_naming.rs
@@ -111,7 +111,7 @@ fn parse(template: &str) -> Result<Vec<Part<'_>>> {
 
 fn expand(parts: &[Part<'_>], name: &str, ext: &str, serial: u32, date: Date) -> String {
     let mut out = String::new();
-    for part in parts {
+    for (index, part) in parts.iter().enumerate() {
         match part {
             Part::Literal(s) => out.push_str(s),
             Part::Name(NameCase::AsIs) => out.push_str(name),
@@ -126,14 +126,20 @@ fn expand(parts: &[Part<'_>], name: &str, ext: &str, serial: u32, date: Date) ->
             Part::Serial(width) => out.push_str(&format!("{serial:0width$}")),
             Part::Letter(upper) => out.push_str(&letters(serial, *upper)),
             Part::Date(kind) => out.push_str(&date.format(*kind)),
-            Part::Ext(false) => out.push_str(ext),
-            Part::Ext(true) => out.push_str(&ext.to_uppercase()),
+            Part::Ext(upper) => {
+                // The reference app adds the separator only for the final extension component.
+                // A literal dot in the template already supplies that separator.
+                if !parts[index + 1..].iter().any(|part| !matches!(part, Part::Literal(""))) && !out.ends_with('.') {
+                    out.push('.');
+                }
+                if *upper {
+                    out.push_str(&ext.to_uppercase());
+                } else {
+                    out.push_str(ext);
+                }
+            }
         }
     }
-    if !parts.iter().any(|part| matches!(part, Part::Ext(_))) {
-        out.push('.');
-        out.push_str(ext);
-    }
     out
 }
 
@@ -162,7 +168,7 @@ pub fn plan(inputs: &[BatchInput], output: &str, format: &str, params: &Value) -
     let timestamp = crate::analysis_cmds::now_iso();
     let date = Date::from_iso(&timestamp).ok_or_else(|| bad("naming: the current UTC date is unavailable"))?;
     let mut outputs = Vec::with_capacity(inputs.len());
-    for (index, BatchInput { path, rel_dir }) in inputs.iter().enumerate() {
+    for (index, BatchInput { path, .. }) in inputs.iter().enumerate() {
         let serial = if has_serial {
             u32::try_from(index).ok().and_then(|index| start.checked_add(index)).ok_or_else(|| bad("startingSerial plus the input count exceeds 4294967295"))?
         } else {
@@ -173,8 +179,8 @@ pub fn plan(inputs: &[BatchInput], output: &str, format: &str, params: &Value) -
         if name.is_empty() || name.ends_with(['.', ' ']) || name.len() > 255 || name.chars().any(|c| c.is_control() || "/\\<>:\"|?*".contains(c)) {
             return Err(bad("naming must produce a nonempty filename of at most 255 bytes without trailing spaces, path separators or reserved characters"));
         }
-        // From subfolders ("Include All Subfolders"), each result keeps its subfolder.
-        outputs.push(join(&join(output, rel_dir), &name));
+        // Photoshop Batch writes all subfolder results into the destination itself.
+        outputs.push(join(output, &name));
     }
     // Renaming within the source folder could replace a later input before it is read. Resolve
     // existing paths so aliases such as `source/./001.png` cannot bypass the check. The default
@@ -201,9 +207,18 @@ mod tests {
     fn substituted_names_are_literal_and_serials_do_not_wrap_or_truncate() {
         let parts = parse("{date}_{name}_{serial}").unwrap();
         let date = Date { year: 2026, month: 10, day: 13 };
-        assert_eq!(expand(&parts, "photo{serial}", "png", 7, date), "2026-10-13_photo{serial}_007.png");
-        assert_eq!(expand(&parts, "photo", "png", 1000, date), "2026-10-13_photo_1000.png");
+        assert_eq!(expand(&parts, "photo{serial}", "png", 7, date), "2026-10-13_photo{serial}_007");
+        assert_eq!(expand(&parts, "photo", "png", 1000, date), "2026-10-13_photo_1000");
         let parts = parse("{NAME}_{Name}_{serial:1}_{letter}{LETTER}_{date:mmddyy}.{EXT}").unwrap();
         assert_eq!(expand(&parts, "my Photo", "png", 27, date), "MY PHOTO_My photo_27_aaAA_101326.PNG");
     }
+
+    #[test]
+    fn extension_component_only_adds_a_dot_at_the_end() {
+        let date = Date { year: 2026, month: 11, day: 1 };
+        for (template, expected) in [("{name}{ext}", "a.png"), ("{name}{ext}{serial}", "apng001"), ("{name}{serial}", "a001"), ("{name}{ext}{ext}", "apng.png")]
+        {
+            assert_eq!(expand(&parse(template).unwrap(), "a", "png", 1, date), expected, "{template}");
+        }
+    }
 }
diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 66c54b0dea..f725f98942 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -1,7 +1,7 @@
 use super::open::import_at_raw_ppi;
 use super::paths::{extension, file_name, join, list_images, read_file, stem};
 use super::processing::parse_steps;
-use super::save::{SaveOpts, save_doc};
+use super::save::{SaveOpts, save_doc, save_doc_as};
 use super::{Arc, Document, EngineError, Result, Session, Value, batch_naming, json, str_param};
 
 /// Inputs of a batch command: `"input"` is a folder or an array of files.
@@ -189,7 +189,7 @@ fn process_outputs<'a>(
     let mut errors = Vec::new();
     let mut written = OutputClaims::default();
     for (path, out) in outputs {
-        let r = process_one(raw_ppi, path, &out, save, &written, f);
+        let r = process_one(raw_ppi, path, &out, save, ProcessOptions { format: None, written: Some(&written), ctx: None }, f);
         match r {
             Ok(()) => {
                 written.record(&out, path);
@@ -201,23 +201,40 @@ fn process_outputs<'a>(
     json!({"files": files, "errors": errors})
 }
 
-fn process_one(raw_ppi: f64, path: &str, out: &str, save: SaveOpts, written: &OutputClaims, f: &dyn Fn(&mut Session, &str) -> Result<bool>) -> Result<()> {
-    written.check(out).map_err(EngineError::Other)?;
+struct ProcessOptions<'a> {
+    format: Option<&'a str>,
+    written: Option<&'a OutputClaims>,
+    ctx: Option<&'a crate::jobs::JobCtx>,
+}
+
+fn process_one(raw_ppi: f64, path: &str, out: &str, save: SaveOpts, options: ProcessOptions<'_>, f: &dyn Fn(&mut Session, &str) -> Result<bool>) -> Result<()> {
+    if let Some(written) = options.written {
+        written.check(out).map_err(EngineError::Other)?;
+    }
     let bytes = read_file(path)?;
     let mut scratch = Session::new();
     let doc = import_at_raw_ppi(raw_ppi, &file_name(path), &bytes)?;
     scratch.add_document(doc, Some(path.to_string()));
-    if !f(&mut scratch, out)? {
+    let saved_by_action = f(&mut scratch, out)?;
+    if let Some(ctx) = options.ctx {
+        ctx.check()?;
+    }
+    if !saved_by_action {
         let d = scratch.active().ok_or(EngineError::NoDocument)?;
-        save_doc(&d.doc, out, save)?;
+        if let Some(format) = options.format {
+            let ext = if format == "same" { same_format(path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
+            save_doc_as(&d.doc, out, &ext, save)?;
+        } else {
+            save_doc(&d.doc, out, save)?;
+        }
     }
     Ok(())
 }
 
 #[derive(Clone, Debug)]
-struct BatchPolicy {
-    stop_on_error: bool,
-    error_log: Option<String>,
+pub(super) struct BatchPolicy {
+    pub(super) stop_on_error: bool,
+    pub(super) error_log: Option<String>,
 }
 
 impl BatchPolicy {
@@ -237,29 +254,38 @@ impl BatchPolicy {
     }
 }
 
-fn write_error_log(path: &str, errors: &[Value]) -> Result<()> {
-    let date = crate::analysis_cmds::now_iso();
-    let mut body = format!("PhotoCraft Batch: {} error(s) on {}\n", errors.len(), date.get(..10).unwrap_or("unknown date"));
-    for error in errors {
-        let input = error.get("file").or_else(|| error.get("document")).and_then(Value::as_str).unwrap_or("?");
-        let reason = error.get("error").and_then(Value::as_str).unwrap_or("?");
-        body.push_str(&format!("{input}: {reason}\n"));
+/// Photoshop-compatible Batch log encoding, shared by the desktop command and CLI.
+pub fn encode_batch_error_log<'a>(errors: impl IntoIterator<Item = (&'a str, &'a str)>) -> Vec<u8> {
+    let mut body = String::from("Batch Start\r\n\r\n");
+    for (input, reason) in errors {
+        body.push_str(&format!("File: \"{input}\"\r\nError: {reason}\r\n\r\n"));
     }
-    super::paths::write_file(path, body.as_bytes()).map_err(|error| EngineError::Other(format!("error log: {error}")))
+    body.push_str("Batch End\r\n");
+    let mut bytes = vec![0xff, 0xfe];
+    for word in body.encode_utf16() {
+        bytes.extend_from_slice(&word.to_le_bytes());
+    }
+    bytes
+}
+
+fn write_error_log(path: &str, errors: &[Value]) -> Result<()> {
+    let bytes = encode_batch_error_log(errors.iter().map(|error| {
+        (error.get("file").or_else(|| error.get("document")).and_then(Value::as_str).unwrap_or("?"), error.get("error").and_then(Value::as_str).unwrap_or("?"))
+    }));
+    super::paths::write_file(path, &bytes).map_err(|error| EngineError::Other(format!("error log: {error}")))
 }
 
 fn error_log_failure(path: Option<&str>, errors: &[Value]) -> Option<String> {
-    path.filter(|_| !errors.is_empty()).and_then(|path| write_error_log(path, errors).err().map(|error| error.to_string()))
+    path.and_then(|path| write_error_log(path, errors).err().map(|error| error.to_string()))
 }
 
 fn batch_outcome(files: Vec<String>, errors: Vec<Value>, stopped: Option<(String, Vec<String>)>, error_log: Option<&str>) -> Value {
-    let logged = !errors.is_empty();
     let mut result = json!({"files": files, "errors": errors});
     if let Some((at, skipped)) = stopped {
         result["stopped"] = json!(at);
         result["skipped"] = json!(skipped);
     }
-    if logged && let Some(path) = error_log {
+    if let Some(path) = error_log {
         result["errorLog"] = json!(path);
     }
     result
@@ -274,9 +300,29 @@ fn validate_error_log(policy: &BatchPolicy, inputs: impl IntoIterator<Item = Str
     Ok(())
 }
 
-fn process_batch_outputs(
+/// A flat Batch result must not replace another input before it is opened. Compare resolved
+/// identities once for the whole plan, so aliases and large folder batches stay safe and linear.
+#[cfg(not(target_arch = "wasm32"))]
+pub fn validate_flat_outputs(outputs: &[(String, String)]) -> Result<()> {
+    let sources: std::collections::HashMap<_, _> =
+        outputs.iter().enumerate().filter_map(|(index, (input, _))| std::fs::canonicalize(input).ok().map(|identity| (identity, index))).collect();
+    for (index, (_, output)) in outputs.iter().enumerate() {
+        let identity = super::paths::destination_identity(std::path::Path::new(output))
+            .ok_or_else(|| EngineError::BadParams { cmd: "file.automate.batch".into(), msg: format!("output path cannot be resolved safely: {output}") })?;
+        if sources.get(&identity).is_some_and(|&source_index| source_index != index) {
+            return Err(EngineError::BadParams {
+                cmd: "file.automate.batch".into(),
+                msg: format!("output would replace another input file: {output}; choose a different destination or naming template"),
+            });
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn process_batch_outputs(
     raw_ppi: f64,
     outputs: Vec<(String, String)>,
+    format: &str,
     save: SaveOpts,
     policy: &BatchPolicy,
     ctx: &crate::jobs::JobCtx,
@@ -285,7 +331,6 @@ fn process_batch_outputs(
     let total = outputs.len();
     let mut files = Vec::new();
     let mut errors = Vec::new();
-    let mut written = OutputClaims::default();
     let mut stopped = None;
     let mut done = 0;
     for (index, (path, out)) in outputs.iter().enumerate() {
@@ -293,11 +338,14 @@ fn process_batch_outputs(
             break;
         }
         ctx.progress(index as f32 / total.max(1) as f32, &format!("{} of {total}: {}", index + 1, file_name(path)));
-        let result = process_one(raw_ppi, path, out, save, &written, f);
+        let result = process_one(raw_ppi, path, out, save, ProcessOptions { format: Some(format), written: None, ctx: Some(ctx) }, f);
+        if ctx.cancelled() {
+            done = index;
+            break;
+        }
         done = index + 1;
         match result {
             Ok(()) => {
-                written.record(out, path);
                 files.push(out.clone());
             }
             Err(error) => {
@@ -440,11 +488,13 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
             .iter()
             .map(|input| {
                 let ext = if format == "same" { same_format(&input.path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
-                let out = join(&join(&output, &input.rel_dir), &format!("{}.{ext}", stem(&input.path)));
+                let out = join(&output, &format!("{}.{ext}", stem(&input.path)));
                 (input.path.clone(), out)
             })
             .collect(),
     };
+    #[cfg(not(target_arch = "wasm32"))]
+    validate_flat_outputs(&outputs)?;
     validate_error_log(&policy, outputs.iter().map(|(input, _)| input.clone()), outputs.iter().map(|(_, output)| output.clone()))?;
     // Each input runs in its own scratch session, so what the played steps spend is carried from
     // one input to the next (failed or not) and back to this session, not restarted per input.
@@ -462,6 +512,8 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                 let result = (|| {
                     // A recorded save marks a result. If the action later closes or switches
                     // documents, write the saved snapshot instead of the new active document.
+                    let source = scratch.active().and_then(|state| state.path.as_deref()).unwrap_or("");
+                    let encode_format = if format == "same" { same_format(source) } else { format.trim_start_matches('.').to_ascii_lowercase() };
                     let mut saved: Option<Arc<Document>> = None;
                     for (id, params) in &steps {
                         if batch_save_point(id) {
@@ -475,7 +527,8 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                     }
                     match saved {
                         Some(doc) if scratch.active().is_none_or(|active| active.doc.id != doc.id) => {
-                            save_doc(&doc, out, save)?;
+                            ctx.check()?;
+                            save_doc_as(&doc, out, &encode_format, save)?;
                             Ok(true)
                         }
                         _ => Ok(false),
@@ -484,7 +537,7 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                 carried.set(scratch.actions.playback_steps);
                 result
             };
-            let result = process_batch_outputs(raw_ppi, outputs, save, &policy, ctx, &run);
+            let result = process_batch_outputs(raw_ppi, outputs, &format, save, &policy, ctx, &run);
             Ok((result, carried.get()))
         },
         move |s, (result, carried)| {
@@ -539,10 +592,9 @@ fn batch_open_documents(
     validate_error_log(policy, originals.iter().map(|(_, _, path)| path.clone()), planned.iter().flat_map(|paths| paths.iter().cloned()))?;
     let mut files = Vec::new();
     let mut errors = Vec::new();
-    let mut claims = OutputClaims::default();
     let mut stopped = None;
     let mut done = 0;
-    for (index, (id, name, _)) in originals.iter().enumerate() {
+    for (index, (id, name, path)) in originals.iter().enumerate() {
         let result = (|| -> Result<()> {
             let position = s.documents().iter().position(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?;
             s.set_active(position);
@@ -559,13 +611,12 @@ fn batch_open_documents(
             }
             let Some(paths) = &planned else { return Ok(()) };
             let out = paths.get(index).ok_or_else(|| EngineError::Other("batch output plan is incomplete".into()))?;
-            claims.check(out).map_err(EngineError::Other)?;
             let doc = match saved {
                 Some(saved) => saved,
                 None => s.documents().iter().find(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?.doc.clone(),
             };
-            save_doc(&doc, out, save)?;
-            claims.record(out, name);
+            let ext = if format == "same" { same_format(path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
+            save_doc_as(&doc, out, &ext, save)?;
             files.push(out.clone());
             Ok(())
         })();
diff --git a/crates/engine/src/cmd/file_cmds/save.rs b/crates/engine/src/cmd/file_cmds/save.rs
index fff62dc7f4..34b5873082 100644
--- a/crates/engine/src/cmd/file_cmds/save.rs
+++ b/crates/engine/src/cmd/file_cmds/save.rs
@@ -211,6 +211,13 @@ pub(crate) fn save_doc(doc: &Document, path: &str, save: impl Into<SaveOpts>) ->
     Ok(warnings)
 }
 
+/// Save Batch bytes in the chosen format even when its naming rules omit or replace the suffix.
+pub(crate) fn save_doc_as(doc: &Document, path: &str, format: &str, save: impl Into<SaveOpts>) -> Result<Vec<String>> {
+    let (bytes, warnings) = encode(doc, format, save)?;
+    write_file(path, &bytes)?;
+    Ok(warnings)
+}
+
 pub(super) fn save_a_copy(s: &mut Session, p: &Value) -> Result<Value> {
     let path = str_param(p, "path", "file.saveACopy")?.to_string();
     let d = s.active().ok_or(EngineError::NoDocument)?;
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 8de4564672..7615c102fb 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -31,6 +31,15 @@ fn composite(s: &Session, x: i32, y: i32) -> [f32; 4] {
     b.px[0]
 }
 
+fn batch_log(path: &str) -> String {
+    let bytes = std::fs::read(path).unwrap();
+    assert!(bytes.starts_with(&[0xff, 0xfe]), "Batch log needs a UTF-16 LE BOM");
+    let (pairs, remainder) = bytes[2..].as_chunks::<2>();
+    assert!(remainder.is_empty(), "UTF-16 bytes must have even length");
+    let words: Vec<u16> = pairs.iter().map(|pair| u16::from_le_bytes(*pair)).collect();
+    String::from_utf16(&words).unwrap()
+}
+
 #[test]
 fn batch_stop_on_error_reports_skipped_inputs_and_writes_the_error_log() {
     let dir = tmp("batch-stop-error-log");
@@ -45,11 +54,41 @@ fn batch_stop_on_error_reports_skipped_inputs_and_writes_the_error_log() {
     assert_eq!(result["errors"].as_array().map(Vec::len), Some(1), "{result}");
     assert_eq!(result["stopped"], json!(missing), "{result}");
     assert_eq!(result["skipped"], json!([good]), "{result}");
-    let text = std::fs::read_to_string(&log).unwrap();
-    assert!(text.contains("missing.png") && text.contains("1 error(s)"), "{text}");
+    let text = batch_log(&log);
+    assert!(text.starts_with("Batch Start\r\n\r\n") && text.contains("missing.png") && text.contains("File: \"") && text.contains("Error: "), "{text}");
+    assert!(text.ends_with("Batch End\r\n"), "{text}");
     assert!(!std::path::Path::new(&join(&output, "good.png")).exists());
 }
 
+#[test]
+fn batch_writes_a_utf16_error_log_even_when_every_file_succeeds() {
+    let dir = tmp("batch-clean-log");
+    let input = png(&dir, "good.png", 8, 6, "#00ff00");
+    let output = join(&dir, "out");
+    let log = join(&dir, "errors.txt");
+    let result = Session::new().execute("file.automate.batch", json!({"steps": [], "input": [input], "output": output, "errorLog": log})).unwrap();
+    assert_eq!(result["errors"], json!([]), "{result}");
+    assert_eq!(result["errorLog"], json!(log));
+    assert_eq!(batch_log(&log), "Batch Start\r\n\r\nBatch End\r\n");
+}
+
+#[test]
+fn batch_cancelled_during_an_action_does_not_save_that_input() {
+    let dir = tmp("batch-cancel-current");
+    let input = png(&dir, "source.png", 8, 6, "#ff0000");
+    let out = join(&dir, "out/source.png");
+    let ctx = crate::jobs::JobCtx::new();
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+    let result = super::batch_run::process_batch_outputs(72.0, vec![(input, out.clone())], "png", SaveOpts::default(), &policy, &ctx, &|_, _| {
+        ctx.cancel();
+        Ok(false)
+    })
+    .unwrap();
+    assert_eq!(result["files"], json!([]), "{result}");
+    assert_eq!(result["cancelled"], json!(true), "{result}");
+    assert!(!std::path::Path::new(&out).exists());
+}
+
 #[test]
 fn batch_error_log_cannot_replace_an_input_or_result() {
     let dir = tmp("batch-error-log-collision");
@@ -78,6 +117,18 @@ fn batch_naming_rejects_an_input_alias_through_a_missing_parent() {
     assert!(!std::path::Path::new(&join(&dir, "missing")).exists());
 }
 
+#[test]
+fn flat_batch_cannot_replace_a_later_unread_input() {
+    let dir = tmp("batch-flat-input-alias");
+    let input_png = png(&dir, "a.png", 8, 6, "#0000ff");
+    let mut s = session(8, 6, 8);
+    save_doc(doc(&s), &join(&dir, "a.jpg"), None).unwrap();
+    let before = std::fs::read(&input_png).unwrap();
+    let result = s.execute("file.automate.batch", json!({"steps": [], "input": dir, "output": dir, "format": "png"}));
+    assert!(result.as_ref().is_err_and(|e| e.to_string().contains("input")), "{result:?}");
+    assert_eq!(std::fs::read(&input_png).unwrap(), before);
+}
+
 #[cfg(unix)]
 #[test]
 fn batch_error_log_rejects_a_symlink_parent_alias() {
@@ -270,7 +321,8 @@ fn batch_same_format_saves_camera_raws_as_psd() {
         let mut files: Vec<String> = r["files"].as_array().unwrap().iter().map(|f| f.as_str().unwrap().replace('\\', "/")).collect();
         files.sort();
         assert_eq!(files.len(), 2, "{r}");
-        assert!(files[0].contains("/IMG_0001") && files[0].ends_with(".psd") && files[1].contains("/b") && files[1].ends_with(".png"), "{files:?}");
+        let suffixes = if naming.is_some() { ("_001", "_002") } else { (".psd", ".png") };
+        assert!(files[0].contains("/IMG_0001") && files[0].ends_with(suffixes.0) && files[1].contains("/b") && files[1].ends_with(suffixes.1), "{files:?}");
         let psd = photocraft_io::import("IMG_0001.psd", &std::fs::read(&files[0]).unwrap()).unwrap().document;
         assert_eq!((psd.size.width, psd.size.height), (w as u32, h as u32));
     }
@@ -1680,16 +1732,16 @@ fn batch_naming_serial_keeps_same_named_inputs_and_their_pixels() {
         )
         .unwrap();
     assert_eq!(result["errors"], json!([]), "{result}");
-    assert_eq!(result["files"], json!([join(&out, "photo_007.png"), join(&out, "photo_008.png")]));
-    for (name, expected) in [("photo_007.png", [1.0, 0.0, 0.0, 1.0]), ("photo_008.png", [0.0, 0.0, 1.0, 1.0])] {
-        let saved = photocraft_io::import(name, &std::fs::read(join(&out, name)).unwrap()).unwrap().document;
+    assert_eq!(result["files"], json!([join(&out, "photo_007"), join(&out, "photo_008")]));
+    for (name, expected) in [("photo_007", [1.0, 0.0, 0.0, 1.0]), ("photo_008", [0.0, 0.0, 1.0, 1.0])] {
+        let saved = photocraft_io::import("photo.png", &std::fs::read(join(&out, name)).unwrap()).unwrap().document;
         let pixel = photocraft_compose::render(&saved, Rect::new(1, 1, 2, 2)).px[0];
         assert_eq!(pixel, expected, "{name}");
     }
 }
 
-/// Two inputs with one output name: the first result is kept and the second is an error, never
-/// a silent overwrite listed as written (#422).
+/// Batch follows Photoshop's later-file-wins behavior. Image Processor and lens correction
+/// keep their existing collision error so their outputs are never silently replaced.
 #[test]
 fn batch_reports_inputs_that_share_an_output_name() {
     let dir = tmp("collide");
@@ -1713,12 +1765,16 @@ fn batch_reports_inputs_that_share_an_output_name() {
         let r = s.execute(cmd, p).unwrap();
         let files = r["files"].as_array().unwrap();
         let errors = r["errors"].as_array().unwrap();
-        // `a.*` and `B.png`/`b.tif` (names that differ only in case) each collide once.
-        assert_eq!((files.len(), errors.len()), (2, 2), "{cmd}: {r}");
-        assert!(errors.iter().all(|e| e["error"].as_str().unwrap().contains("not written")), "{r}");
-        let mut written: Vec<_> = files.iter().map(|f| f.as_str().unwrap().to_lowercase()).collect();
-        written.dedup();
-        assert_eq!(written.len(), 2, "each listed file is distinct: {r}");
+        if cmd == "file.automate.batch" {
+            assert_eq!((files.len(), errors.len()), (4, 0), "{cmd}: {r}");
+            assert_eq!(files[1], files[2], "the later a.png result replaces a.jpg: {r}");
+        } else {
+            assert_eq!((files.len(), errors.len()), (2, 2), "{cmd}: {r}");
+            assert!(errors.iter().all(|e| e["error"].as_str().unwrap().contains("not written")), "{r}");
+            let mut written: Vec<_> = files.iter().map(|f| f.as_str().unwrap().to_lowercase()).collect();
+            written.dedup();
+            assert_eq!(written.len(), 2, "each listed file is distinct: {r}");
+        }
     }
     // Keeping each file's format, nothing collides.
     let out = join(&dir, "same");
@@ -1732,10 +1788,10 @@ fn batch_reports_inputs_that_share_an_output_name() {
     std::fs::write(&droplet, json!({"photocraftDroplet": 1, "name": "d", "action": {"steps": []}, "options": {"format": "png"}}).to_string()).unwrap();
     let out = join(&dir, "droplet");
     let r = s.execute("file.automate.runDroplet", json!({"droplet": droplet, "input": [join(&input, "a.png"), other], "output": out})).unwrap();
-    assert_eq!((r["files"].as_array().unwrap().len(), r["errors"].as_array().unwrap().len()), (1, 1), "{r}");
+    assert_eq!((r["files"].as_array().unwrap().len(), r["errors"].as_array().unwrap().len()), (2, 0), "{r}");
     let kept = photocraft_io::import("a.png", &std::fs::read(join(&out, "a.png")).unwrap()).unwrap().document;
     let px = photocraft_compose::render(&kept, Rect::new(1, 1, 2, 2)).px[0];
-    assert!(px[0] > 0.99 && px[1] < 0.01, "the first input's result is kept: {px:?}");
+    assert!(px[0] > 0.99 && px[1] > 0.99, "the later input's result replaces the first: {px:?}");
 }
 
 /// `file.revealInFinder` (the document tab's Reveal, UI-217-6) reveals the clicked document's
@@ -1793,7 +1849,7 @@ fn batch_include_all_subfolders() {
     let out = join(&input, "batch");
     let r = s.execute("file.automate.batch", json!({"steps": [], "input": input, "output": out, "format": "png"})).unwrap();
     assert_eq!((r["files"].as_array().unwrap().len(), r["errors"].as_array().unwrap().len()), (1, 0), "{r}");
-    // With subfolders: every image, in folder order, results kept apart by subfolder; the output
+    // With subfolders: every image, in folder order, results saved flat; the output
     // folder (inside the input folder, holding last run's a.png) is not an input.
     let r = s
         .execute(
@@ -1804,12 +1860,12 @@ fn batch_include_all_subfolders() {
     assert!(r["errors"].as_array().unwrap().is_empty(), "{r}");
     let files: Vec<String> = r["files"].as_array().unwrap().iter().map(|f| f.as_str().unwrap().replace('\\', "/")).collect();
     let o = out.replace('\\', "/");
-    assert_eq!(files, vec![format!("{o}/a.png"), format!("{o}/sub/b.png"), format!("{o}/sub/deeper/a.png"), format!("{o}/z/a.png")]);
-    let deep = photocraft_io::import("a.png", &std::fs::read(join(&out, "sub/deeper/a.png")).unwrap()).unwrap().document;
-    let px = photocraft_compose::render(&deep, Rect::new(1, 1, 2, 2)).px[0];
-    assert!(px[0] > 0.99 && px[1] > 0.99 && px[2] < 0.01, "blue inverted to yellow: {px:?}");
+    assert_eq!(files, vec![format!("{o}/a.png"), format!("{o}/b.png"), format!("{o}/a.png"), format!("{o}/a.png")]);
+    let last = photocraft_io::import("a.png", &std::fs::read(join(&out, "a.png")).unwrap()).unwrap().document;
+    let px = photocraft_compose::render(&last, Rect::new(1, 1, 2, 2)).px[0];
+    assert!(px[0] < 0.01 && px[1] < 0.01 && px[2] < 0.01, "the last white input is inverted to black: {px:?}");
     std::fs::remove_dir_all(&out).unwrap();
-    // A naming template applies within each kept subfolder (output outside the input folder).
+    // A naming template applies across all inputs, with serials distinguishing the flat outputs.
     let named = join(&dir, "named");
     let r = s
         .execute("file.automate.batch", json!({"steps": [], "input": input, "includeSubfolders": true, "output": named, "format": "png", "naming": "{serial}"}))
@@ -1817,7 +1873,7 @@ fn batch_include_all_subfolders() {
     assert!(r["errors"].as_array().unwrap().is_empty(), "{r}");
     let files: Vec<String> = r["files"].as_array().unwrap().iter().map(|f| f.as_str().unwrap().replace('\\', "/")).collect();
     let n = named.replace('\\', "/");
-    assert_eq!(files, vec![format!("{n}/001.png"), format!("{n}/sub/002.png"), format!("{n}/sub/deeper/003.png"), format!("{n}/z/004.png")]);
+    assert_eq!(files, vec![format!("{n}/001"), format!("{n}/002"), format!("{n}/003"), format!("{n}/004")]);
     // Image Processor shares the option (with its results out of the input folder).
     let out = join(&dir, "jpg");
     let r = s.execute("file.scripts.imageProcessor", json!({"input": input, "includeSubfolders": true, "output": out})).unwrap();
@@ -1930,13 +1986,13 @@ fn batch_naming_keeps_serial_positions_after_errors_and_captures_the_utc_date()
     assert_eq!(files.len(), 1, "{result}");
     let name = file_name(files[0].as_str().unwrap());
     assert!(
-        name == format!("{}_010_good.png", &before[..10]) || name == format!("{}_010_good.png", &after[..10]),
+        name == format!("{}_010_good", &before[..10]) || name == format!("{}_010_good", &after[..10]),
         "the missing input still consumes its serial: {name}"
     );
 }
 
 #[test]
-fn batch_naming_still_reports_collisions_instead_of_overwriting() {
+fn batch_naming_later_result_replaces_the_earlier_one() {
     let dir = tmp("naming-collision");
     let red = png(&dir, "red.png", 8, 8, "#ff0000");
     let blue = png(&dir, "blue.png", 8, 8, "#0000ff");
@@ -1950,11 +2006,10 @@ fn batch_naming_still_reports_collisions_instead_of_overwriting() {
             }),
         )
         .unwrap();
-    assert_eq!(result["files"], json!([join(&out, "constant.png")]));
-    assert_eq!(result["errors"].as_array().unwrap().len(), 1, "{result}");
-    assert!(result["errors"][0]["error"].as_str().unwrap().contains("not written"));
-    let saved = photocraft_io::import("constant.png", &std::fs::read(join(&out, "constant.png")).unwrap()).unwrap().document;
-    assert_eq!(photocraft_compose::render(&saved, Rect::new(1, 1, 2, 2)).px[0], [1.0, 0.0, 0.0, 1.0]);
+    assert_eq!(result["files"], json!([join(&out, "constant"), join(&out, "constant")]));
+    assert_eq!(result["errors"], json!([]), "{result}");
+    let saved = photocraft_io::import("constant.png", &std::fs::read(join(&out, "constant")).unwrap()).unwrap().document;
+    assert_eq!(photocraft_compose::render(&saved, Rect::new(1, 1, 2, 2)).px[0], [0.0, 0.0, 1.0, 1.0]);
 }
 #[test]
 fn batch_naming_rejects_outputs_that_replace_inputs_before_processing() {
@@ -1969,7 +2024,7 @@ fn batch_naming_rejects_outputs_that_replace_inputs_before_processing() {
         .execute(
             "file.automate.batch",
             json!({
-                "input": [first, second], "output": join(&dir, "."), "steps": [], "naming": "{serial}"
+                "input": [first, second], "output": join(&dir, "."), "steps": [], "naming": "{serial}.{ext}"
             }),
         )
         .unwrap_err();
diff --git a/docs/batch-naming.md b/docs/batch-naming.md
index caa17e78e2..3a5ed716a8 100644
--- a/docs/batch-naming.md
+++ b/docs/batch-naming.md
@@ -2,8 +2,8 @@
 
 Select a recorded action, then open **File > Automate > Batch**. Source can be a folder (with
 **Include All Subfolders**) or the open documents. **File Naming** accepts a template. Leave it
-blank to keep source filenames and collision reporting. A template without `{ext}` gets the
-chosen output extension appended.
+blank to keep source stems with the selected output extension. An explicit template spells the
+whole filename; without `{ext}`, no extension is added.
 
 | Token | Value |
 | --- | --- |
@@ -12,15 +12,21 @@ chosen output extension appended.
 | `{letter}`, `{LETTER}` | Serial letters: a … z, aa …; uppercase with `{LETTER}` |
 | `{date}` | UTC date at the start of the batch, in `YYYY-MM-DD` form |
 | `{date:mmddyy}`, `{date:mmdd}`, `{date:yyyymmdd}`, `{date:yymmdd}`, `{date:yyddmm}`, `{date:ddmmyy}` | Other UTC date arrangements |
-| `{ext}`, `{EXT}` | Output extension, lowercase or uppercase |
+| `{ext}`, `{EXT}` | Output extension, lowercase or uppercase; a dot is added when this is the final component, unless the template already supplied one |
 
-For example, `{name}_{serial}` with starting serial 7 writes `photo_007.png` and
-`photo_008.png` for two PNG inputs named `photo.png`. A serial after 999 becomes 1000;
+For example, `{name}_{serial}` with starting serial 7 writes `photo_007` and
+`photo_008` for two PNG inputs named `photo.png`; `{name}_{serial}{ext}` writes
+`photo_007.png` and `photo_008.png`. The file bytes still use the selected output format.
+A serial after 999 becomes 1000;
 it does not wrap. Folder inputs use the existing filename order, and an explicit input array
 keeps its order. Failed inputs consume their position, so later filenames do not shift.
-Braces in an input filename are literal text, not additional tokens. Subfolder inputs keep their
-relative folders under the output folder. **Stop On Error** leaves later inputs unprocessed;
-**Error Log** records failures and their reasons. Folder batches report progress per file and
+Braces in an input filename are literal text, not additional tokens. Batch writes subfolder
+inputs flat into the output folder in input order. A later same-name result replaces an earlier
+one, as measured in Photoshop 2026. **Stop On Error** leaves later inputs unprocessed;
+**Error Log** writes a UTF-16 LE file with a BOM and CRLF line endings even when no file fails.
+It starts with `Batch Start`, records a `File` / `Error` pair per failure, and ends with
+`Batch End`. The wording is English because PhotoCraft does not have Photoshop's numeric error
+codes or German message catalog. Folder batches report progress per file and
 can be cancelled after the current file. A cancelled batch returns `cancelled: true`, its
 completed `files`, and `skipped` inputs. If writing the error log fails, the batch still
 returns its per-file results with `errorLogError` instead of `errorLog`.
@@ -28,10 +34,11 @@ returns its per-file results with `errorLogError` instead of `errorLog`.
 Unknown tokens, unmatched braces, invalid parameter types, path separators, reserved filename
 characters, excessive filename length (255 UTF-8 bytes), and serial overflow are rejected before
 export writes begin. Starting serial must be an integer from 1 to 4,294,967,295.
-A custom template that resolves to an existing input file is also rejected; choose a separate
-destination or another template. Ordinary per-file read, action and save failures still appear
-in the batch's `errors` result. When two results share a name, including a case-only difference,
-the first successful result is kept and the later collision is reported.
+A custom template that resolves to an existing input file is also rejected before processing;
+the same guard checks default flat output names. This prevents an early result from destroying
+a later unread input. Ordinary per-file read,
+action and save failures still appear in the batch's `errors` result. Image Processor and lens
+correction continue to report output-name collisions.
 
 The same options are available on `file.automate.batch` through the engine command interface:
 
@@ -47,4 +54,16 @@ The same options are available on `file.automate.batch` through the engine comma
 ```
 
 The CLI has matching `batch --recursive`, `--naming`, `--start-serial`, `--stop-on-error`, and
-`--error-log` flags. Image Processor and droplet options retain their existing behavior.
+`--error-log` flags. Droplets use Batch's flat output and naming behavior.
+
+## Reference behavior and conformance
+
+The [Photoshop 2026 Batch measurements](https://github.com/davidmann4/photocraft/blob/docs/atn-event-reference/docs/atn.md#batch-behaviour)
+record flat subfolder output, last-result-wins collisions, and extension components that add a
+dot only at the end. `batch_include_all_subfolders`,
+`batch_naming_later_result_replaces_the_earlier_one`, and
+`extension_component_only_adds_a_dot_at_the_end` check those cases. PhotoCraft deliberately
+rejects a plan that would replace another input file before it is read, to prevent data loss.
+It keeps a progress display and immediate cancellation in the UI so headless control clients can
+observe and stop a batch. The measured Photoshop dialog has no progress display and asks whether
+to continue or stop after Esc; those differences remain open under AUTO-219-5.
diff --git a/docs/gaps.md b/docs/gaps.md
index cad521f003..955a0ffad4 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -1,6 +1,6 @@
 # Where PhotoCraft falls short of Photoshop
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-01 · **Change:** minor (G11: Batch folder recursion, live open-document source, extended naming, stop/error log and folder-job progress/cancel, #4579; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-02 · **Change:** minor (G11: Batch measured output naming and UTF-16 log corrections; remaining progress and cancel prompt parity tracked, #4579; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 Every known shortfall against Photoshop 2026 (27.11.0), one entry each, ranked by user impact
 on the way to beta. This is the work list agents pick from: take the highest-ranked entry that
@@ -111,10 +111,12 @@ what an agent can't finish alone.
 - **Estimate:** 120–200 h.
 
 ### G11. Actions and scripting
-- **Done 2026-11-01 (#4579):** Batch accepts recursive folders with mirrored output folders or
-  live open documents, extended file naming tokens, stop-on-error, an error-log file, and job
-  progress/cancel for folder input. The CLI exposes the same folder options. AUTO-219-5 is done;
-  no readiness percentage or estimate changed.
+- **Partial 2026-11-02 (#4579):** Batch accepts recursive folders with flat output and
+  last-result-wins names, as measured in Photoshop 2026. It also accepts live open documents,
+  extended naming components, stop-on-error, UTF-16 LE logs, and job cancellation. The CLI
+  exposes the folder options. AUTO-219-5 remains partial: the UI shows job progress and cancels
+  directly instead of opening Photoshop's Continue/Stop prompt; scratch sessions do not show
+  each input in the window. No readiness percentage or estimate changed.
 - **2026-10-21 evidence (#8304):** Save Actions expands compound layer-property edits into
   separate Photoshop Set events, with rename last so named layer references remain valid.
   Exported descriptors and native playback at RGB 8/16/32-bit have [regression coverage](../crates/engine/src/atn_cmds/layer_props_tests.rs);
@@ -124,8 +126,8 @@ what an agent can't finish alone.
   in the document being played; missing comps stop playback. Other reference forms stay kept
   Photoshop steps and are reported as unsupported. AUTO-219-2 remains partial.
 - **2026-10-13 evidence:** Batch supports [output naming templates](batch-naming.md) using
-  `{name}`, `{serial}` and a captured UTC `{date}`, with a starting serial number. Colliding
-  names remain errors; custom output names cannot replace inputs. AUTO-219-5 stays partial.
+  `{name}`, `{serial}` and a captured UTC `{date}`, with a starting serial number. Custom output
+  names cannot replace inputs before they are read. AUTO-219-5 stays partial.
 - **Missing:** document-independent action recording (AUTO-219-1) and ExtendScript/UXP
   compatibility. `.atn` steps outside the
   mapped events (paths, scripts, Generative Fill, Filter Gallery effects other than Spatter,
@@ -428,6 +430,7 @@ what an agent can't finish alone.
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | G11: measured Batch output is flat and later results replace earlier ones; naming spells the whole filename; UTF-16 LE logs; current progress and cancellation UI tracked as remaining parity work (#4579); AUTO-219-5 partial; readiness and estimate unchanged |
 | 2026-11-01 | minor | G11: Batch recursion, open-document source, extended naming, stop/error log and folder-job progress/cancel (#4579); AUTO-219-5 done; readiness and estimate unchanged |
 | 2026-10-27 | minor | Smooth/Feather command reads and replacement use selection bounds plus blur reach; full-canvas reference and release comparisons extended; percentages and scorecard budgets unchanged |
 | 2026-11-01 | minor | G9: 11 of 183 preferences do nothing (was 12): Graphics Adapter (`performance.gpuAdapter`) always worked, but startup read it by raw JSON key, which the scorecard prefs audit can't see; it now reads the typed Performance section; no estimate changed |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index d7e5696809..f5686f16cf 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -11,7 +11,7 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
 | [Tools](#tools) | 36 | 9 | 0 |  |
 | [Workspace and UI](#workspace-and-ui) | 15 | 6 | 2 | settings that do nothing: 11 of 183 (target 0) |
 | [Type](#type) | 5 | 5 | 0 |  |
-| [Automation](#automation) | 6 | 1 | 4 | 631 of 631 menu items live (100.0%) |
+| [Automation](#automation) | 5 | 2 | 4 | 631 of 631 menu items live (100.0%) |
 | [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 30 of 30 crates; panic_hunt present |
 | [Distribution](#distribution) | 5 | 5 | 1 |  |
 | [Open bugs](#open-bugs) | 31 | 1 | 0 |  |
@@ -259,7 +259,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
-| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | done | [#219](https://github.com/storytold/photocraft/issues/219) | file_cmds/batch_run.rs and batch_naming.rs: bounded recursive folder input with mirrored output folders; live open-document source; full Batch naming tokens and serials; per-file progress and cancellation for folder jobs; stop-on-error with skipped inputs and an optional error-log file; CLI flags and Batch dialog, #4579 |
+| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | partial | [#219](https://github.com/storytold/photocraft/issues/219) | file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. The UI still shows background progress and cancels immediately instead of showing Photoshop's Continue/Stop prompt; folder processing uses scratch sessions rather than opening each file in the window. |
 | AUTO-219-6 | Plug-in ABI v2: panel kind, progress/cancel calls, read other layers, Last Filter repeats | missing | [#219](https://github.com/storytold/photocraft/issues/219) | runtime.rs:15 ABI_VERSION = 1; manifest.rs:18 Kind::Filter only |
 | AUTO-219-7 | Local ONNX models behind a flag, managed in Preferences; subject select, background removal | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No ONNX runtime dependency |
 | AUTO-219-8 | xtask check that every panel button routes through a command id | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No such xtask check |
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index 12fbd733d6..845a698121 100644
--- a/docs/target-app-parity.md
+++ b/docs/target-app-parity.md
@@ -1,6 +1,6 @@
 # PhotoCraft vs Adobe Photoshop: target-app parity
 
-> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-01 · **Change:** minor (Automation Batch now covers recursive folders, open documents, naming, error handling and folder-job progress/cancel, AUTO-219-5 done, #4579; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-02 · **Change:** minor (Automation Batch output naming and UTF-16 logs now follow measured Photoshop behavior; progress and cancel prompt remain partial, AUTO-219-5, #4579; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 The authoritative answer to "how close is PhotoCraft to Photoshop, and how much work is left". The
 one-page summary is [`ROADMAP.md`](../ROADMAP.md); the ranked work list is [`gaps.md`](gaps.md);
@@ -184,7 +184,9 @@ parity for the area and are already contained in the dimension rows above.
 | AI / generative | 10% | 300–600 | See the dimension row |
 
 Batch supports [output naming templates, recursive folders, open documents, per-file progress,
-cancellation, stop-on-error and error logs](batch-naming.md); AUTO-219-5 is done (#4579).
+cancellation, stop-on-error and error logs](batch-naming.md); measured output names and UTF-16
+logs match Photoshop 2026, while the progress display and Continue/Stop cancellation prompt
+remain different. AUTO-219-5 is partial (#4579).
 
 ## Remaining effort and calibration
 
@@ -586,6 +588,7 @@ See [method, raw measurements and reproduction](five-algorithm-performance.md).
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | Automation Batch: flat subfolder output, last-result-wins naming and UTF-16 LE logs matched to measured Photoshop 2026; progress and cancel prompt remain partial, AUTO-219-5 (#4579); percentages and estimates unchanged |
 | 2026-11-01 | minor | Automation Batch: recursive folders, open documents, extended naming, stop/error log and folder-job progress/cancel; AUTO-219-5 done (#4579); percentages and estimates unchanged |
 | 2026-11-01 | minor | UI / UX and Workspace rows: 11 of 183 preferences do nothing (was 12); Graphics Adapter always worked, but startup read it by raw JSON key, which the scorecard audit can't see. Percentages and estimates unchanged |
 | 2026-10-27 | minor | Smooth/Feather command reads and replacement use selection bounds plus blur reach; full-canvas reference and release comparisons extended; percentages and scorecard budgets unchanged |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index 52a73fae38..89c337903c 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -42,9 +42,9 @@ note = "actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document record
 [[item]]
 id = "AUTO-219-5"
 target = "Batch: subfolders, open documents, naming template, progress/cancel, error log, stop"
-status = "done"
+status = "partial"
 issue = 219
-note = "file_cmds/batch_run.rs and batch_naming.rs: bounded recursive folder input with mirrored output folders; live open-document source; full Batch naming tokens and serials; per-file progress and cancellation for folder jobs; stop-on-error with skipped inputs and an optional error-log file; CLI flags and Batch dialog, #4579"
+note = "file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. The UI still shows background progress and cancels immediately instead of showing Photoshop's Continue/Stop prompt; folder processing uses scratch sessions rather than opening each file in the window."
 
 [[item]]
 id = "AUTO-219-6"

From f14da98cc33a262b0714990e8490f8e8a0a5529c Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 11:36:46 -0600
Subject: [PATCH 060/109] Resolve Batch log aliases in future output
 directories

---
 crates/engine/src/cmd/file_cmds/paths.rs | 30 +++++++++++++++++-------
 crates/engine/src/cmd/file_cmds/tests.rs | 27 +++++++++++++++++++++
 2 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index e0cf4433cb..1aead2eaec 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -219,11 +219,8 @@ pub fn destination_identity(path: &std::path::Path) -> Option<std::path::PathBuf
 /// Probe the actual destination directory. macOS volumes and Windows directories may use either
 /// case behavior; the OS name alone cannot tell whether two future names will alias.
 #[cfg(any(target_os = "macos", target_os = "windows"))]
-fn case_sensitive_destination(path: &std::path::Path) -> Option<bool> {
-    let parent = path.parent()?;
-    if !std::fs::metadata(parent).ok()?.is_dir() {
-        return None;
-    }
+pub(super) fn case_sensitive_destination(path: &std::path::Path) -> Option<bool> {
+    let parent = path.ancestors().skip(1).find(|ancestor| ancestor.is_dir())?;
     let probe = tempfile::Builder::new().prefix(".PhotoCraftCaseProbe-").tempfile_in(parent).ok()?;
     let name = probe.path().file_name()?.to_str()?;
     let alternate = parent.join(name.replacen("PhotoCraft", "photocraft", 1));
@@ -234,6 +231,24 @@ fn case_sensitive_destination(path: &std::path::Path) -> Option<bool> {
     }
 }
 
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+fn resolved_paths_match(a: &std::path::Path, b: &std::path::Path, case_sensitive: Option<bool>) -> bool {
+    if a == b {
+        return true;
+    }
+    match (a.to_str(), b.to_str()) {
+        (Some(a_text), Some(b_text)) if a_text.to_lowercase() == b_text.to_lowercase() => !case_sensitive.unwrap_or(false),
+        _ => false,
+    }
+}
+
+#[cfg(all(test, any(target_os = "macos", target_os = "windows")))]
+#[test]
+fn identical_resolved_paths_conflict_on_a_case_sensitive_volume() {
+    let path = std::path::Path::new("/future/result.png");
+    assert!(resolved_paths_match(path, path, Some(true)));
+}
+
 /// Whether two paths would name the same destination even before the file exists. This is used
 /// when a batch error log must not be allowed to replace a result that will be written later.
 pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path::Path>) -> bool {
@@ -247,10 +262,7 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
             (Some(a), Some(b)) => {
                 #[cfg(any(target_os = "windows", target_os = "macos"))]
                 {
-                    match (a.to_str(), b.to_str()) {
-                        (Some(a_text), Some(b_text)) if a_text.to_lowercase() == b_text.to_lowercase() => !case_sensitive_destination(&a).unwrap_or(false),
-                        _ => a == b,
-                    }
+                    if a == b { true } else { resolved_paths_match(&a, &b, case_sensitive_destination(&a)) }
                 }
                 #[cfg(not(any(target_os = "windows", target_os = "macos")))]
                 {
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 7615c102fb..6c2ec4a8ce 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -147,6 +147,19 @@ fn batch_error_log_rejects_a_symlink_parent_alias() {
     assert!(!std::path::Path::new(&join(&output, "result.png")).exists());
 }
 
+#[test]
+fn batch_error_log_rejects_an_uncreated_output_alias() {
+    let dir = tmp("batch-error-log-future-alias");
+    let input = png(&dir, "source.png", 8, 6, "#ff0000");
+    let output = join(&dir, "new-output");
+    std::fs::create_dir_all(join(&output, "alias")).unwrap();
+    let log = join(&output, "alias/../source.png");
+    assert!(same_destination(&log, join(&output, "source.png")));
+    let error = Session::new().execute("file.automate.batch", json!({"steps": [], "input": [input], "output": output, "errorLog": log})).unwrap_err();
+    assert!(error.to_string().contains("errorLog"), "{error}");
+    assert!(!std::path::Path::new(&join(&dir, "new-output/source.png")).exists());
+}
+
 #[cfg(target_os = "linux")]
 #[test]
 fn linux_distinct_case_destinations_are_not_the_same_file() {
@@ -164,6 +177,20 @@ fn unicode_case_variants_follow_destination_volume() {
     assert_eq!(same_destination(join(&dir, "Ä.png"), join(&dir, "ä.png")), volume_aliases_case);
 }
 
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+#[test]
+fn future_folder_case_variants_follow_the_nearest_existing_ancestor() {
+    let dir = tmp("batch-future-folder-case");
+    let existing = join(&dir, "Ä-probe");
+    std::fs::write(&existing, b"probe").unwrap();
+    let volume_aliases_case = same_file(&existing, join(&dir, "ä-probe"));
+    let first = join(&dir, "new/nested/Image.png");
+    let second = join(&dir, "new/nested/image.png");
+    assert_eq!(super::paths::case_sensitive_destination(std::path::Path::new(&first)), Some(!volume_aliases_case));
+    assert_eq!(same_destination(first, second), volume_aliases_case);
+    assert!(!std::path::Path::new(&join(&dir, "new")).exists());
+}
+
 #[test]
 fn batch_open_source_edits_each_live_document_and_restores_the_active_one() {
     let dir = tmp("batch-open-documents");

From 07bc258bbd0a07fd035ae8a1e5e2b564724b32f6 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 11:37:52 -0600
Subject: [PATCH 061/109] Avoid case probes for unrelated Batch paths

---
 crates/engine/src/cmd/file_cmds/paths.rs | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index 1aead2eaec..642389ed3d 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -232,12 +232,12 @@ pub(super) fn case_sensitive_destination(path: &std::path::Path) -> Option<bool>
 }
 
 #[cfg(any(target_os = "macos", target_os = "windows"))]
-fn resolved_paths_match(a: &std::path::Path, b: &std::path::Path, case_sensitive: Option<bool>) -> bool {
+fn resolved_paths_match(a: &std::path::Path, b: &std::path::Path, case_sensitive: impl FnOnce() -> Option<bool>) -> bool {
     if a == b {
         return true;
     }
     match (a.to_str(), b.to_str()) {
-        (Some(a_text), Some(b_text)) if a_text.to_lowercase() == b_text.to_lowercase() => !case_sensitive.unwrap_or(false),
+        (Some(a_text), Some(b_text)) if a_text.to_lowercase() == b_text.to_lowercase() => !case_sensitive().unwrap_or(false),
         _ => false,
     }
 }
@@ -246,7 +246,8 @@ fn resolved_paths_match(a: &std::path::Path, b: &std::path::Path, case_sensitive
 #[test]
 fn identical_resolved_paths_conflict_on_a_case_sensitive_volume() {
     let path = std::path::Path::new("/future/result.png");
-    assert!(resolved_paths_match(path, path, Some(true)));
+    assert!(resolved_paths_match(path, path, || Some(true)));
+    assert!(!resolved_paths_match(path, std::path::Path::new("/future/other.png"), || panic!("unrelated names must not probe the volume")));
 }
 
 /// Whether two paths would name the same destination even before the file exists. This is used
@@ -262,7 +263,7 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
             (Some(a), Some(b)) => {
                 #[cfg(any(target_os = "windows", target_os = "macos"))]
                 {
-                    if a == b { true } else { resolved_paths_match(&a, &b, case_sensitive_destination(&a)) }
+                    resolved_paths_match(&a, &b, || case_sensitive_destination(&a))
                 }
                 #[cfg(not(any(target_os = "windows", target_os = "macos")))]
                 {

From b27b5c7a79abd04f53c7300e16b808f3c4b842b4 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 12:39:15 -0600
Subject: [PATCH 062/109] Update Batch UI tests for flat filenames

---
 crates/ui-egui/src/menus/view_cmds/tests.rs     | 7 ++++++-
 crates/ui-egui/tests/it/batch_export_options.rs | 2 +-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/crates/ui-egui/src/menus/view_cmds/tests.rs b/crates/ui-egui/src/menus/view_cmds/tests.rs
index dae8f8c62c..29ff24e44d 100644
--- a/crates/ui-egui/src/menus/view_cmds/tests.rs
+++ b/crates/ui-egui/src/menus/view_cmds/tests.rs
@@ -447,7 +447,12 @@ fn batch_dialogs_include_all_subfolders() {
         fields.insert("includeSubfolders".into(), json!(true));
         let r = crate::dialogs::confirm(&mut app, d).unwrap();
         assert_eq!(r["files"].as_array().map(Vec::len), Some(1), "{id}: {r}");
-        assert!(dir.join(out).join("sub").is_dir(), "{id} keeps the subfolder: {r}");
+        if id == "file.automate.batch" {
+            assert!(dir.join(out).join("a.png").is_file(), "{id} writes subfolder inputs flat: {r}");
+            assert!(!dir.join(out).join("sub").exists());
+        } else {
+            assert!(dir.join(out).join("sub").is_dir(), "{id} keeps the subfolder: {r}");
+        }
     }
     let _ = std::fs::remove_dir_all(&dir);
 }
diff --git a/crates/ui-egui/tests/it/batch_export_options.rs b/crates/ui-egui/tests/it/batch_export_options.rs
index 980331a91f..1890f6dd9e 100644
--- a/crates/ui-egui/tests/it/batch_export_options.rs
+++ b/crates/ui-egui/tests/it/batch_export_options.rs
@@ -290,7 +290,7 @@ fn batch_naming_controls_export_the_requested_names_and_reset_on_cancel() {
     edit_path(&mut h, "Output", &output);
     h.get_by_role_and_label(egui::accesskit::Role::TextInput, "File Naming").click();
     h.run_steps(2);
-    replace_text(&mut h, "{serial}_{name}");
+    replace_text(&mut h, "{serial}_{name}.{ext}");
     h.get_by_role_and_label(egui::accesskit::Role::SpinButton, "Starting serial").click();
     h.run_steps(2);
     h.event(egui::Event::Text("7".into()));

From b22384aab895f6989312aa0350a92e5766cb99fa Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 12:44:46 -0600
Subject: [PATCH 063/109] Release action snapshot before closed-document
 scratch buffers

---
 crates/engine/src/jobs.rs | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index c4d22b9520..aadb667633 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -886,7 +886,7 @@ impl Session {
         // Commands this one runs on its own behalf journal after this mark (#3067).
         let nested_from = self.journal.len();
         let pre_selected = if self.actions.recording.is_some() { self.active().map(|st| st.selected_layers()) } else { None };
-        let record_before = crate::actions_record::Before::capture(self);
+        let mut record_before = crate::actions_record::Before::capture(self);
         // A replayable command is recorded as one step, so recording pauses while it runs: an
         // action it plays (a script step) must not flush the steps it ran so far into the action
         // being recorded, nor move the recording mark past the entries it is about to replace.
@@ -924,7 +924,7 @@ impl Session {
                 job.journal = spec.journal;
                 job.recorded_by = self.actions.recording.map(|_| self.actions.take);
                 job.pre_selected = pre_selected.clone();
-                job.before = record_before;
+                job.before = std::mem::take(&mut record_before);
                 let jid = job.id;
                 self.jobs.running.push(job);
                 Ok(Started::Job(jid))
@@ -948,11 +948,12 @@ impl Session {
                 Ok(Started::Done(v))
             }
         };
-        // A closed document's freed buffers went to the scratch pool (`before` kept the active
-        // one alive until here): hand them back to the OS (#10479). Compared by id, since Split
-        // and Merge Channels close documents while opening others.
+        // A closed document's freed buffers went to the scratch pool (`before` and the action
+        // recording snapshot kept it alive until here). Drop both before handing the pool back
+        // to the OS (#10479). Compare ids since Split/Merge Channels open replacement documents.
         if docs_before.iter().any(|id| !self.docs.iter().any(|st| st.doc.id == *id)) {
             drop(before);
+            drop(record_before);
             photocraft_raster::scratch::release();
         }
         out

From 61c72186f628923c754301bdd04acb05a159b0f2 Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Mon, 2 Nov 2026 20:03:32 +0100
Subject: [PATCH 064/109] Crop: a Shift-corner drag follows the frame's
 diagonal (#10871)

With a free ratio, Shift on a crop corner kept the proportions by letting
the larger relative extent win, so (-100, -50) on an 800 x 500 frame gave
720 x 450. Photoshop projects the pointer onto the frame's diagonal through
the dragged corner and gives 706 x 441. Do the same, with and without Auto
Center Preview and on a turned frame. A ratio preset, Alt+Shift and edge
handles keep today's rule.
---
 crates/ui-egui/src/tools/crop_ui.rs          | 32 ++++++-
 crates/ui-egui/tests/it/crop_shift_corner.rs | 96 ++++++++++++++++++++
 crates/ui-egui/tests/it/main.rs              |  1 +
 3 files changed, 125 insertions(+), 4 deletions(-)
 create mode 100644 crates/ui-egui/tests/it/crop_shift_corner.rs

diff --git a/crates/ui-egui/src/tools/crop_ui.rs b/crates/ui-egui/src/tools/crop_ui.rs
index 3a05ba2cc7..a1588ea7e6 100644
--- a/crates/ui-egui/src/tools/crop_ui.rs
+++ b/crates/ui-egui/src/tools/crop_ui.rs
@@ -8,8 +8,8 @@
 //!   being drawn;
 //! - inside the frame, a drag moves it;
 //! - on an edge or corner, a drag resizes it along the frame's own (possibly turned) axes; ⇧ keeps
-//!   the frame's aspect ratio, ⌥ resizes about the centre, and an options-bar ratio preset always
-//!   holds;
+//!   the frame's aspect ratio (on a corner the pointer is followed along the frame's diagonal),
+//!   ⌥ resizes about the centre, and an options-bar ratio preset always holds;
 //! - outside the frame (off its handles) the pointer is the rotate cursor and a drag turns the
 //!   frame about its centre, ⇧ in 15° steps, with the angle beside the pointer (#1792). As in
 //!   Photoshop, a new frame is drawn after the pending one is committed or cancelled;
@@ -204,6 +204,23 @@ pub fn resized_turned(r: [f64; 4], deg: f64, hx: i8, hy: i8, d: [f64; 2], ratio:
     [nc[0] - hw, nc[1] - hh, nc[0] + hw, nc[1] + hh]
 }
 
+/// Drag `d` on corner (`hx`, `hy`) of frame `r` turned `deg` degrees, projected onto the frame's
+/// diagonal through that corner: a ⇧ corner drag with a free ratio slides the corner along it, as
+/// in Photoshop (#10871). A corner drag on a ratio otherwise lets the larger relative extent win,
+/// so (−100, −50) on 800 × 500 gave 720 × 450 instead of Photoshop's 706 × 441.
+fn along_diagonal(r: [f64; 4], deg: f64, hx: i8, hy: i8, d: [f64; 2]) -> [f64; 2] {
+    let v = turn([f64::from(hx) * (r[2] - r[0]), f64::from(hy) * (r[3] - r[1])], [0.0, 0.0], deg);
+    let vv = v[0] * v[0] + v[1] * v[1];
+    let t = (d[0] * v[0] + d[1] * v[1]) / vv;
+    if vv > 0.0 && t.is_finite() { [t * v[0], t * v[1]] } else { d }
+}
+
+/// ⇧ on a corner with no ratio preset and no ⌥: the corner follows the frame's diagonal
+/// ([`along_diagonal`]). A preset, ⌥ ⇧ and the edge handles keep the larger-extent rule.
+fn follows_diagonal(app: &PhotocraftApp, hx: i8, hy: i8, mods: Modifiers) -> bool {
+    mods.shift && !mods.alt && hx != 0 && hy != 0 && preset_ratio(app).is_none()
+}
+
 /// `[x0, y0, x1, y1]` with x0 ≤ x1, y0 ≤ y1.
 fn normalized(a: [f64; 2], b: [f64; 2]) -> [f64; 4] {
     [a[0].min(b[0]), a[1].min(b[1]), a[0].max(b[0]), a[1].max(b[1])]
@@ -935,9 +952,13 @@ fn follow_view_drag(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> bo
         }
         Some(CropDrag::Resize { hx, hy, start, rect, view: Some(view) }) => {
             // Auto Center Preview keeps the box centred while the handle follows the pointer.
-            let at = crate::crop_mode::to_press(app, Some(view), p);
+            let mut at = crate::crop_mode::to_press(app, Some(view), p);
             let ratio = resize_ratio(app, rect, mods);
             let deg = angle(app);
+            if follows_diagonal(app, hx, hy, mods) {
+                let d = along_diagonal(rect, deg, hx, hy, [at[0] - start[0], at[1] - start[1]]);
+                at = [start[0] + d[0], start[1] + d[1]];
+            }
             crate::crop_mode::live_resize(app, crate::crop_mode::LiveResize { rect, deg, hx, hy, start, q: at, ratio, alt: mods.alt }, view);
         }
         _ => return false,
@@ -950,6 +971,7 @@ fn dragged_frame(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> Optio
     let ratio = preset_ratio(app);
     let space = app.crop.space;
     let deg = angle(app);
+    let diagonal = matches!(app.crop.drag, Some(CropDrag::Resize { hx, hy, .. }) if follows_diagonal(app, hx, hy, mods));
     match app.crop.drag.as_mut()? {
         CropDrag::Draw { anchor, cur, last, .. } => {
             if space {
@@ -973,7 +995,9 @@ fn dragged_frame(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> Optio
                 (w > 0.0 && h > 0.0).then(|| w / h)
             };
             let ratio = ratio.or_else(|| if mods.shift { keep() } else { None });
-            Some(resized_turned(*rect, deg, *hx, *hy, [p[0] - start[0], p[1] - start[1]], ratio, mods.alt))
+            let d = [p[0] - start[0], p[1] - start[1]];
+            let d = if diagonal { along_diagonal(*rect, deg, *hx, *hy, d) } else { d };
+            Some(resized_turned(*rect, deg, *hx, *hy, d, ratio, mods.alt))
         }
         CropDrag::Rotate { .. } | CropDrag::TurnImage { .. } | CropDrag::MoveImage { .. } => None,
     }
diff --git a/crates/ui-egui/tests/it/crop_shift_corner.rs b/crates/ui-egui/tests/it/crop_shift_corner.rs
new file mode 100644
index 0000000000..6fba00ed02
--- /dev/null
+++ b/crates/ui-egui/tests/it/crop_shift_corner.rs
@@ -0,0 +1,96 @@
+//! Crop tool: ⇧-dragging a frame corner keeps its proportions by following the pointer along the
+//! frame's diagonal, as Photoshop does (#10871).
+//!
+//! Measured in Photoshop: 800 × 500 document, frame = whole canvas, free ratio, Auto Center
+//! Preview off, ⇧-drag of the bottom-right corner by (−100, −50) px commits 706 × 441 (the drag
+//! projected onto (800, 500) shortens the frame by 11.8 %). PhotoCraft let the larger relative
+//! extent win and committed 720 × 450.
+//!
+//! Driven through `ui.pointer`, as an agent or the canvas sends the drag; no GPU needed.
+
+use photocraft_doc::{Color, ColorMode, Document, SampleType, Size};
+use photocraft_ui_egui::PhotocraftApp;
+use photocraft_ui_egui::control::{ControlRequest, Outcome, handle};
+use serde_json::{Value, json};
+
+/// An 800 × 500 document at 100 % in a canvas it fits, the Crop tool's default frame up.
+fn crop_app(auto_center: bool) -> PhotocraftApp {
+    let doc = Document::with_background("crop", Size::new(800, 500), ColorMode::Rgb, SampleType::U8, Color::WHITE);
+    let mut s = photocraft_engine::Session::new();
+    s.add_document(doc, None);
+    let mut app = PhotocraftApp::new(s, Default::default());
+    app.sync_views();
+    app.ui.extras.snap = false;
+    app.ui.extras.rulers = false;
+    app.ui.view.show.smart_guides = false;
+    app.last_canvas_rect = egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(1600.0, 1000.0));
+    let v = &mut app.ui.views[0];
+    (v.zoom, v.center, v.fit_pending, v.rotation) = (1.0, [400.0, 250.0], false, 0.0);
+    app.ui.tool_options.crop_shield.auto_center_preview = auto_center;
+    pointer(&mut app, json!({"tool": "Crop", "events": []}));
+    photocraft_ui_egui::crop_ui::ensure_frame(&mut app);
+    assert_eq!(app.ui.crop_rect, Some([0.0, 0.0, 800.0, 500.0]), "the default frame is the whole canvas");
+    app
+}
+
+fn pointer(app: &mut PhotocraftApp, params: Value) {
+    let ctx = egui::Context::default();
+    let (req, _rx) = ControlRequest::new("ui.pointer", params);
+    let Outcome::Done(v) = handle(app, &ctx, &req) else { panic!("ui.pointer didn't finish") };
+    assert_eq!(v["ok"], true, "{v}");
+}
+
+/// Drags the bottom-right corner by `d` in steps, holding `mods`, and commits with ↵.
+fn drag_corner_and_commit(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) -> (u32, u32) {
+    let (x, y) = (800.0, 500.0);
+    let mut events = vec![json!({"kind": "down", "x": x, "y": y})];
+    events.extend((1..=4).map(|i| {
+        let t = f64::from(i) / 4.0;
+        json!({"kind": "move", "x": x + d[0] * t, "y": y + d[1] * t})
+    }));
+    events.push(json!({"kind": "up", "x": x + d[0], "y": y + d[1]}));
+    let mut params = mods;
+    params["events"] = Value::Array(events);
+    pointer(app, params);
+    photocraft_ui_egui::canvas::commit_crop(app);
+    let size = app.session.active().expect("a document").doc.size;
+    (size.width, size.height)
+}
+
+fn assert_near(got: (u32, u32), want: (u32, u32), what: &str) {
+    let off = |a: u32, b: u32| a.abs_diff(b);
+    assert!(off(got.0, want.0) <= 1 && off(got.1, want.1) <= 1, "{what}: committed {got:?}, want {want:?} ±1 px");
+}
+
+#[test]
+fn shift_corner_drag_follows_the_frames_diagonal() {
+    let mut app = crop_app(false);
+    let got = drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true}));
+    assert_near(got, (706, 441), "⇧ drag by (−100, −50)");
+}
+
+#[test]
+fn shift_corner_drag_outward_past_the_canvas_follows_the_diagonal() {
+    let mut app = crop_app(false);
+    // (100, 50) onto (800, 500) grows the frame by 11.8 %: 894.4 × 559.0, past the canvas.
+    let got = drag_corner_and_commit(&mut app, [100.0, 50.0], json!({"shift": true}));
+    assert_near(got, (894, 559), "⇧ drag by (100, 50)");
+}
+
+#[test]
+fn shift_corner_drag_keeps_the_proportions_with_auto_center_preview() {
+    let mut app = crop_app(true);
+    let (w, h) = drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true}));
+    assert!(w < 800 && h < 500, "the frame shrank: {w} × {h}");
+    assert!((f64::from(w) / f64::from(h) - 1.6).abs() < 0.01, "8 : 5 kept: {w} × {h}");
+}
+
+#[test]
+fn the_same_drag_without_shift_or_with_alt_is_unchanged() {
+    // No ⇧: the corner follows the pointer freely, 700 × 450 as in Photoshop.
+    let mut app = crop_app(false);
+    assert_near(drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({})), (700, 450), "no ⇧");
+    // ⌥ ⇧ (not measured, today's rule): about the centre, 600 × 400 grows to 8 : 5 as 640 × 400.
+    let mut app = crop_app(false);
+    assert_near(drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true, "alt": true})), (640, 400), "⌥ ⇧");
+}
diff --git a/crates/ui-egui/tests/it/main.rs b/crates/ui-egui/tests/it/main.rs
index e8d8b334ba..ce1e6f77f2 100644
--- a/crates/ui-egui/tests/it/main.rs
+++ b/crates/ui-egui/tests/it/main.rs
@@ -13,6 +13,7 @@ mod color_managed_canvas;
 mod crop_beyond_canvas;
 mod crop_default_mode;
 mod crop_popup_keys;
+mod crop_shift_corner;
 mod custom_print_paper;
 mod display_shadows;
 mod drag_preview_canvas;

From 3e52046ed35f84d377c4358ff7cd9a9948236221 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 13:47:31 -0600
Subject: [PATCH 065/109] docs: clarify recorded layer selection behavior

---
 docs/control-protocol.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 7cb6f7fc32..f488ee9316 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped unless it supplies source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`); other layers are recorded by their unique names, while `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped only when it is the sole selected layer and does not supply source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`). Otherwise, including when several layers are selected, it is recorded by its unique name; `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |

From 50670f9d67ef6afed5ac4b2e3dbe0dc5d39dda90 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 13:54:58 -0600
Subject: [PATCH 066/109] fix: preserve active batch edits and cancellation
 result

---
 crates/engine/src/cmd/file_cmds/batch_run.rs |  1 +
 crates/engine/src/cmd/file_cmds/paths.rs     |  2 +-
 crates/engine/src/cmd/file_cmds/tests.rs     | 21 +++++++--
 crates/engine/src/jobs.rs                    | 17 ++++++-
 crates/engine/src/jobs/tests.rs              | 35 +++++++++++++++
 crates/ui-egui/src/jobs_ui.rs                |  1 +
 crates/ui-egui/src/jobs_ui/tests.rs          | 47 +++++++++++++++-----
 docs/batch-naming.md                         |  4 +-
 docs/control-protocol.md                     |  2 +-
 9 files changed, 111 insertions(+), 19 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index f725f98942..f135b40e77 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -612,6 +612,7 @@ fn batch_open_documents(
             let Some(paths) = &planned else { return Ok(()) };
             let out = paths.get(index).ok_or_else(|| EngineError::Other("batch output plan is incomplete".into()))?;
             let doc = match saved {
+                Some(saved) if s.active().is_some_and(|state| state.doc.id == saved.id) => s.active().ok_or(EngineError::NoDocument)?.doc.clone(),
                 Some(saved) => saved,
                 None => s.documents().iter().find(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?.doc.clone(),
             };
diff --git a/crates/engine/src/cmd/file_cmds/paths.rs b/crates/engine/src/cmd/file_cmds/paths.rs
index 642389ed3d..928325e92f 100644
--- a/crates/engine/src/cmd/file_cmds/paths.rs
+++ b/crates/engine/src/cmd/file_cmds/paths.rs
@@ -270,7 +270,7 @@ pub fn same_destination(a: impl AsRef<std::path::Path>, b: impl AsRef<std::path:
                     a == b
                 }
             }
-            _ => false,
+            _ => true,
         }
     }
     #[cfg(target_arch = "wasm32")]
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 6c2ec4a8ce..ba4bd51510 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -215,7 +215,7 @@ fn batch_open_source_edits_each_live_document_and_restores_the_active_one() {
 }
 
 #[test]
-fn batch_open_source_exports_the_document_at_the_save_point() {
+fn batch_open_source_exports_later_edits_if_saved_document_stays_active() {
     let dir = tmp("batch-open-save-point");
     let mut session = Session::new();
     session.execute("file.new", json!({"name": "First", "width": 8, "height": 6})).unwrap();
@@ -224,7 +224,7 @@ fn batch_open_source_exports_the_document_at_the_save_point() {
         .execute(
             "file.automate.batch",
             json!({
-                "source": "open", "steps": [["document.activate", {"document": 1}], ["file.save", {}]],
+                "source": "open", "steps": [["document.activate", {"document": 1}], ["file.save", {}], ["image.imageRotation.90cw", {}]],
                 "output": dir, "format": "png", "naming": "{name}.{ext}"
             }),
         )
@@ -232,7 +232,22 @@ fn batch_open_source_exports_the_document_at_the_save_point() {
     assert!(result["errors"].as_array().unwrap().is_empty(), "{result}");
     let mut opened = Session::new();
     opened.execute("file.openAs", json!({"path": join(&dir, "First.png"), "as": "png"})).unwrap();
-    assert_eq!(doc(&opened).size.width, 12, "the save point selected the second document");
+    assert_eq!((doc(&opened).size.width, doc(&opened).size.height), (5, 12), "the still-active saved document includes later edits");
+}
+
+#[cfg(unix)]
+#[test]
+fn batch_error_log_rejects_a_dangling_link_to_a_planned_output() {
+    use std::os::unix::fs::symlink;
+    let dir = tmp("batch-dangling-error-log-alias");
+    let input = png(&dir, "source.png", 8, 6, "#ff0000");
+    let output = join(&dir, "out");
+    let result = join(&output, "source.png");
+    let log = join(&dir, "errors.txt");
+    symlink(&result, &log).unwrap();
+    let error = Session::new().execute("file.automate.batch", json!({"steps": [], "input": [input], "output": output, "errorLog": log})).unwrap_err();
+    assert!(error.to_string().contains("errorLog"), "{error}");
+    assert!(!std::path::Path::new(&result).exists(), "the batch must not write before rejecting the alias");
 }
 
 #[test]
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index 10d3114e85..f167deae32 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -204,7 +204,7 @@ pub struct JobInfo {
     pub progress: f32,
     pub message: String,
     pub elapsed_ms: f64,
-    /// The command's result (done) or the error (failed).
+    /// The command's result (done), including partial outputs from a cancelled batch.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub result: Option<Value>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -1044,7 +1044,17 @@ impl Session {
             Err(e) => JobOutcome::Failed(e.to_string()),
             Ok(_) if job.ctx.cancelled() && job.command != "file.automate.batch" => JobOutcome::Cancelled,
             Ok(payload) => match self.apply_job(&job, apply, payload) {
-                Ok(v) => JobOutcome::Done(v),
+                Ok(mut v) => {
+                    // A batch may take its final cancellation snapshot before the worker
+                    // finishes. A cancellation accepted during that interval still counts.
+                    if job.command == "file.automate.batch"
+                        && job.ctx.cancelled()
+                        && let Some(result) = v.as_object_mut()
+                    {
+                        result.insert("cancelled".into(), Value::Bool(true));
+                    }
+                    JobOutcome::Done(v)
+                }
                 Err(EngineError::Cancelled) => JobOutcome::Cancelled,
                 Err(e) => JobOutcome::Failed(e.to_string()),
             },
@@ -1139,6 +1149,9 @@ impl Session {
         // and discarded results whose document was closed or changed.
         self.live_commit = None;
         let (state, result, error) = match &outcome {
+            JobOutcome::Done(v) if job.command == "file.automate.batch" && v.get("cancelled").and_then(Value::as_bool) == Some(true) => {
+                ("cancelled", Some(v.clone()), None)
+            }
             JobOutcome::Done(v) => ("done", Some(v.clone()), None),
             JobOutcome::Failed(e) => ("failed", None, Some(e.clone())),
             JobOutcome::Cancelled => ("cancelled", None, None),
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index da07db5002..4249c809ac 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -567,6 +567,41 @@ fn cancelled_batch_job_returns_its_partial_result() {
     assert_eq!(result["files"], json!(["done.png"]));
     assert_eq!(result["skipped"], json!(["later.png"]));
     assert_eq!(result["cancelled"], true);
+    let info = s.jobs_with_recent().into_iter().find(|info| info.id == id).unwrap();
+    assert_eq!(info.state, "cancelled");
+    assert_eq!(info.result.unwrap()["files"], json!(["done.png"]));
+    assert!(matches!(s.wait_job(id), Err(EngineError::Cancelled)));
+}
+
+#[test]
+fn accepted_batch_cancellation_after_result_snapshot_is_reported() {
+    let mut s = Session::new();
+    let (ready_tx, ready_rx) = std::sync::mpsc::channel();
+    let (resume_tx, resume_rx) = std::sync::mpsc::channel();
+    let id = job(s
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            move |ctx| {
+                let cancelled = ctx.cancelled();
+                ready_tx.send(()).unwrap();
+                resume_rx.recv().unwrap();
+                Ok(json!({"files": ["done.png"], "cancelled": cancelled}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap());
+    ready_rx.recv_timeout(Duration::from_secs(10)).unwrap();
+    assert!(s.cancel_job(id));
+    resume_tx.send(()).unwrap();
+    let event = wait_event(&mut s, id);
+    let JobOutcome::Done(result) = event.outcome else { panic!("batch result was discarded") };
+    assert_eq!(result["cancelled"], true);
+    assert_eq!(result["files"], json!(["done.png"]));
+    let info = s.jobs_with_recent().into_iter().find(|info| info.id == id).unwrap();
+    assert_eq!(info.state, "cancelled");
 }
 
 #[test]
diff --git a/crates/ui-egui/src/jobs_ui.rs b/crates/ui-egui/src/jobs_ui.rs
index 83bd7e2753..bdc641468e 100644
--- a/crates/ui-egui/src/jobs_ui.rs
+++ b/crates/ui-egui/src/jobs_ui.rs
@@ -461,6 +461,7 @@ fn on_event(app: &mut PhotocraftApp, ctx: &egui::Context, e: JobEvent) {
     }
     // Control requests waiting on this job.
     let reply = match &e.outcome {
+        JobOutcome::Done(v) if cancelled_batch => json!({"ok": false, "error": "cancelled", "result": v}),
         JobOutcome::Done(v) => json!({"ok": true, "result": v}),
         JobOutcome::Failed(err) => json!({"ok": false, "error": err}),
         JobOutcome::Cancelled => json!({"ok": false, "error": "cancelled"}),
diff --git a/crates/ui-egui/src/jobs_ui/tests.rs b/crates/ui-egui/src/jobs_ui/tests.rs
index 12f6b0901d..e33db9df8d 100644
--- a/crates/ui-egui/src/jobs_ui/tests.rs
+++ b/crates/ui-egui/src/jobs_ui/tests.rs
@@ -757,20 +757,45 @@ fn cancelled_batch_with_partial_results_reports_cancellation_without_beeping() {
     BEEPS.store(0, Ordering::Relaxed);
     let mut h = app_harness_with(crate::Services { beep: Some(count_beep), ..Default::default() });
     h.state_mut().run("prefs.set", json!({"path": "general.beepWhenDone", "value": true})).unwrap();
+    let Started::Job(id) = h
+        .state_mut()
+        .session
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            |ctx| {
+                while !ctx.cancelled() {
+                    std::thread::sleep(Duration::from_millis(1));
+                }
+                Ok(json!({"files": ["done.png"], "cancelled": true}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap()
+    else {
+        panic!("batch did not start as a job")
+    };
+    assert!(h.state_mut().session.cancel_job(id));
+    let started = Instant::now();
+    let event = loop {
+        if let Some(event) = h.state_mut().session.poll_jobs().into_iter().find(|event| event.id == id) {
+            break event;
+        }
+        assert!(started.elapsed() < Duration::from_secs(10), "batch did not finish");
+        std::thread::sleep(Duration::from_millis(1));
+    };
     let ctx = h.ctx.clone();
-    crate::jobs_ui::on_event(
-        h.state_mut(),
-        &ctx,
-        photocraft_engine::jobs::JobEvent {
-            id: JobId(9999),
-            command: "file.automate.batch".into(),
-            label: "Batch".into(),
-            document: None,
-            outcome: photocraft_engine::jobs::JobOutcome::Done(json!({"files": ["done.png"], "cancelled": true})),
-        },
-    );
+    let (reply_tx, reply_rx) = std::sync::mpsc::channel();
+    h.state_mut().jobs.waiters.push((id, reply_tx));
+    crate::jobs_ui::on_event(h.state_mut(), &ctx, event);
     assert!(h.state().ui.status.contains("Cancelled"), "{}", h.state().ui.status);
     assert_eq!(BEEPS.load(Ordering::Relaxed), 0);
+    let reply = reply_rx.recv_timeout(Duration::from_secs(1)).unwrap();
+    assert_eq!(reply["ok"], false);
+    assert_eq!(reply["error"], "cancelled");
+    assert_eq!(reply["result"]["files"], json!(["done.png"]));
 }
 
 #[test]
diff --git a/docs/batch-naming.md b/docs/batch-naming.md
index 3a5ed716a8..b0e1b4bd4b 100644
--- a/docs/batch-naming.md
+++ b/docs/batch-naming.md
@@ -28,7 +28,9 @@ It starts with `Batch Start`, records a `File` / `Error` pair per failure, and e
 `Batch End`. The wording is English because PhotoCraft does not have Photoshop's numeric error
 codes or German message catalog. Folder batches report progress per file and
 can be cancelled after the current file. A cancelled batch returns `cancelled: true`, its
-completed `files`, and `skipped` inputs. If writing the error log fails, the batch still
+completed `files`, and `skipped` inputs. Background job status is `cancelled` and retains
+the partial result; a waiting control request replies with `ok: false`, `error: "cancelled"`,
+and that result. If writing the error log fails, the batch still
 returns its per-file results with `errorLogError` instead of `errorLog`.
 
 Unknown tokens, unmatched braces, invalid parameter types, path separators, reserved filename
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index b5f0dca68e..584e20801a 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -250,7 +250,7 @@ The shape is pinned by a test in `crates/automation/src/rpc.rs` (#3684).
 
 ### Background jobs (#210)
 
-Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged; a folder Batch can already have written earlier output files and reports those paths when cancelled. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
+Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged; a folder Batch can already have written earlier output files. A cancelled Batch has `state: "cancelled"` with its partial `result` in `jobs.list`; a waiting control request receives `{"ok":false,"error":"cancelled","result":…}`. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
 
 ## Preferences
 

From 0d27191cb7e572fa827f836f550b8856608a8056 Mon Sep 17 00:00:00 2001
From: Psychotoxical <171614930+Psychotoxical@users.noreply.github.com>
Date: Mon, 2 Nov 2026 21:07:53 +0100
Subject: [PATCH 067/109] Layers panel: keep filtering while the filter row is
 hidden
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Filter Options › Hide hides the row but keeps the filter applied, as in the
reference application (#10876, #10877). This PR now only draws the row in
every theme.
---
 crates/ui-egui/src/panels/layer_filter_ui.rs  |  5 ----
 .../src/panels/layer_filter_ui/tests.rs       | 27 -------------------
 2 files changed, 32 deletions(-)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui.rs b/crates/ui-egui/src/panels/layer_filter_ui.rs
index ba207ef3af..fd035f3284 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui.rs
@@ -31,12 +31,7 @@ pub struct Filter {
 }
 
 impl Filter {
-    /// A hidden filter row filters nothing: the criteria stay for when it's shown again, but no
-    /// layer may go missing from the panel without the row that says why.
     pub fn of(ui: &UiState) -> Self {
-        if !ui.layers_panel_options.show_filters {
-            return Self { by: FilterBy::Kind, kinds: Vec::new(), name: String::new(), mode: ui.layer_filter_mode };
-        }
         Self { by: ui.layer_filter_by, kinds: ui.layer_filter.clone(), name: ui.layer_filter_name.clone(), mode: ui.layer_filter_mode }
     }
 
diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index ecbdc0d240..7dcbeeded3 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -157,30 +157,3 @@ fn every_theme_shows_the_filter_row() {
         assert_eq!(drawn(&h), ["ink notes"], "{theme:?} filters by kind");
     }
 }
-
-/// A filter set while the row was shown stops filtering once the row is hidden, so no layer goes
-/// missing without the row that says why; showing the row again brings the filter back.
-#[test]
-fn a_hidden_filter_row_filters_nothing() {
-    let mut h = harness_in(ThemeKind::Studio);
-    h.state_mut().ui.layer_filter = vec!["type".into()];
-    h.run_steps(4);
-    assert_eq!(drawn(&h), ["ink notes"]);
-    h.state_mut().ui.layers_panel_options.show_filters = false;
-    h.run_steps(4);
-    assert!(h.query_by_value("Kind").is_none(), "the row is hidden");
-    assert_eq!(drawn(&h), ["ink notes", "Sheets", "Ink", "Paper", "Background"]);
-    assert_eq!(h.state().ui.layer_filter, ["type"], "the criteria are kept");
-    h.state_mut().ui.layers_panel_options.show_filters = true;
-    h.run_steps(4);
-    assert_eq!(drawn(&h), ["ink notes"]);
-}
-
-#[test]
-fn a_hidden_filter_row_makes_the_filter_inactive() {
-    let mut ui = UiState { layer_filter_by: FilterBy::Mode, layer_filter_name: "ink".into(), ..UiState::default() };
-    ui.layer_filter = vec!["pixel".into()];
-    assert!(Filter::of(&ui).active());
-    ui.layers_panel_options.show_filters = false;
-    assert!(!Filter::of(&ui).active());
-}

From e451cafeba68c5857a68adecff82d4079a219c70 Mon Sep 17 00:00:00 2001
From: Daktyl198 <dakky198@gmail.com>
Date: Mon, 2 Nov 2026 21:40:41 +0000
Subject: [PATCH 068/109] Actions: relabel only this save's own Save As as File
 > Save, and keep a picked extension's case (#5305)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/app/files.rs                  | 13 ++++++++-----
 crates/ui-egui/src/dialogs/disk_change_prompt.rs |  3 ++-
 crates/ui-egui/src/dialogs/file_ui/web.rs        |  4 +---
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/crates/ui-egui/src/app/files.rs b/crates/ui-egui/src/app/files.rs
index 35267df061..fb79a57aa2 100644
--- a/crates/ui-egui/src/app/files.rs
+++ b/crates/ui-egui/src/app/files.rs
@@ -215,9 +215,10 @@ impl PhotocraftApp {
                 {
                     return r;
                 }
+                let from = app.session.journal.len();
                 let r = app.save_to(path.clone(), choices)?;
                 if plain_save && own.as_deref() == Some(path.as_str()) {
-                    app.journal_as_plain_save(&path);
+                    app.journal_as_plain_save(&path, from);
                 }
                 Ok(r)
             })
@@ -344,8 +345,9 @@ impl PhotocraftApp {
     /// Re-label the Save As just journaled for `path` as File › Save (see [`Self::save_dialog_flow`]),
     /// keeping its Targa, DDS or JPEG answer so playback writes the file the same way. A save
     /// parked behind Targa, DDS or JPEG Options hasn't been journaled yet: it is recorded as
-    /// File › Save once answered.
-    pub(crate) fn journal_as_plain_save(&mut self, path: &str) {
+    /// File › Save once answered. Only a step journaled at index `from` or later (by this save)
+    /// is re-labeled.
+    pub(crate) fn journal_as_plain_save(&mut self, path: &str, from: usize) {
         let parked = [
             self.targa_options.as_mut().map(|p| (&p.path, &mut p.record)),
             self.dds_options.as_mut().map(|p| (&p.path, &mut p.record)),
@@ -359,8 +361,9 @@ impl PhotocraftApp {
         // played on the same way. Any other answer (TIFF layers) keeps the Save As.
         // A Save As that kept the document's own name was recorded as its folder (#5305); the
         // document now has that file, so it resolves back to `path`.
-        let recorded = self.session.journal.last().filter(|last| last.0 == "file.saveAs").and_then(|last| self.recorded_save_path(&last.1).ok());
-        if recorded.as_deref() == Some(path)
+        let journal = &self.session.journal;
+        let recorded = journal.last().filter(|last| last.0 == "file.saveAs" && journal.len() > from).and_then(|last| self.recorded_save_path(&last.1).ok());
+        if recorded.is_some_and(|r| std::path::Path::new(&r) == std::path::Path::new(path))
             && let Some(last) = self.session.journal.last_mut()
             && let Some(step) = last.1.as_object()
             && step
diff --git a/crates/ui-egui/src/dialogs/disk_change_prompt.rs b/crates/ui-egui/src/dialogs/disk_change_prompt.rs
index 34d83075e1..06727c7a8b 100644
--- a/crates/ui-egui/src/dialogs/disk_change_prompt.rs
+++ b/crates/ui-egui/src/dialogs/disk_change_prompt.rs
@@ -50,8 +50,9 @@ pub fn confirm(app: &mut PhotocraftApp, fields: &Map<String, Value>) -> Result<V
     let choices = crate::FormatChoices::from_step(&Value::Object(fields.clone()), "file.save")?;
     app.with_document(doc, |app| {
         if flat {
+            let from = app.session.journal.len();
             let r = app.save_to(path.clone(), choices)?;
-            app.journal_as_plain_save(&path);
+            app.journal_as_plain_save(&path, from);
             Ok(r)
         } else {
             app.save_in_place(path, crate::FormatChoices::default())
diff --git a/crates/ui-egui/src/dialogs/file_ui/web.rs b/crates/ui-egui/src/dialogs/file_ui/web.rs
index 406ff4d7a4..5a14f2a3e0 100644
--- a/crates/ui-egui/src/dialogs/file_ui/web.rs
+++ b/crates/ui-egui/src/dialogs/file_ui/web.rs
@@ -562,9 +562,7 @@ pub(super) fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Re
 fn kept_name_folder(path: &str, base: &str, ext: &str) -> Option<String> {
     let file = std::path::Path::new(path);
     let portable = photocraft_engine::file_cmds::portable_device_name(base.to_string()) == base;
-    let kept = portable
-        && file.file_stem().is_some_and(|s| s.to_string_lossy() == base)
-        && file.extension().is_some_and(|e| e.to_string_lossy().eq_ignore_ascii_case(ext));
+    let kept = portable && file.file_stem().is_some_and(|s| s.to_string_lossy() == base) && file.extension().is_some_and(|e| e.to_string_lossy() == ext);
     kept.then(|| file.parent().map(|d| d.to_string_lossy().into_owned()).unwrap_or_default())
 }
 

From 0306fafb9b169fc3420c6db03ac5375a61e5773b Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 15:58:29 -0600
Subject: [PATCH 069/109] Preserve active spelling layer in recorded actions

---
 crates/engine/src/actions_record.rs      |  2 +-
 crates/engine/src/cmd/type_spell_cmds.rs | 16 ++++++++++++++++
 docs/control-protocol.md                 |  2 +-
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/actions_record.rs b/crates/engine/src/actions_record.rs
index 82781750b2..4bfb54befa 100644
--- a/crates/engine/src/actions_record.rs
+++ b/crates/engine/src/actions_record.rs
@@ -42,7 +42,7 @@ impl Before {
 
 /// Commands whose explicit `layer` names source content rather than a default target.
 pub(crate) fn needs_source_layer(id: &str) -> bool {
-    matches!(id, "layer.new.frame" | "select.loadSelection" | "type.createSelection")
+    matches!(id, "layer.new.frame" | "select.loadSelection" | "type.createSelection" | "edit.checkSpelling")
 }
 
 /// `params` with its `layer` id made portable (see the module doc).
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index f06bfb15f6..1f4339dfd9 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -331,6 +331,22 @@ mod tests {
         assert_eq!(text_of(&s, id), "The");
     }
 
+    #[test]
+    fn a_recorded_spelling_change_keeps_the_active_source_layer() {
+        let (mut s, id) = session("Teh");
+        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
+        let replay = s.active().unwrap().doc.as_ref().clone();
+        s.execute("actions.record", json!({"name": "Fix active spelling"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        let steps = s.execute("actions.get", json!({"action": "Fix active spelling"})).unwrap()["steps"].clone();
+        assert_eq!(steps[0][1]["layer"], name, "the change must retain its source layer");
+        s.add_document(replay, None);
+        let played = s.execute("actions.play", json!({"action": "Fix active spelling"})).unwrap();
+        assert!(played.get("failed").is_none(), "{played}");
+        assert_eq!(text_of(&s, id), "The");
+    }
+
     #[test]
     fn missing_named_spelling_layer_is_an_error_for_list_and_change_all() {
         let (mut s, _) = session("Teh");
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index f488ee9316..48e1ff9d06 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped only when it is the sole selected layer and does not supply source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`). Otherwise, including when several layers are selected, it is recorded by its unique name; `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped only when it is the sole selected layer and does not supply source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`, `edit.checkSpelling`). Otherwise, including when several layers are selected, it is recorded by its unique name; `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |

From 95a7d211c2feb3b621bb2916f8ffd9045211c96a Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 15:59:20 -0600
Subject: [PATCH 070/109] Correct Batch command naming and folder docs

---
 crates/engine/src/cmd/file_cmds.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/engine/src/cmd/file_cmds.rs b/crates/engine/src/cmd/file_cmds.rs
index 58cb9c0d00..ff3f5b9d90 100644
--- a/crates/engine/src/cmd/file_cmds.rs
+++ b/crates/engine/src/cmd/file_cmds.rs
@@ -310,7 +310,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Batch…",
             &["File", "Automate"],
             None,
-            r##"{"steps":[[commandId,params]|{"command":id,"params":{}}…] (a recorded action; Save/Save As marks the result),"source":"folder|open"="folder" (open: run on live open documents),"input":folder|[paths] (folder source),"includeSubfolders":bool=false (up to 32 levels and 100000 files, outputs mirror subfolders),"output":folder (optional for open source),"format":"same|png|jpg|psd|tiff|…"="same","naming":string? (tokens: {name}/{NAME}/{Name}, {serial}/{serial:1..4}, {letter}/{LETTER}, {date} and date formats, {ext}/{EXT}; without {ext}, append the output extension),"startingSerial":1..4294967295=1,"stopOnError":bool=false,"errorLog":path? (blank disables it),"quality":0..12?,"calledActions":[{"name","steps"}…]?} → {files, errors, stopped?, skipped?, errorLog?, documents?} (folder batches report per-file job progress and support cancellation)"##,
+            r##"{"steps":[[commandId,params]|{"command":id,"params":{}}…] (a recorded action; Save/Save As marks the result),"source":"folder|open"="folder" (open: run on live open documents),"input":folder|[paths] (folder source),"includeSubfolders":bool=false (up to 32 levels and 100000 files, outputs are flat under output),"output":folder (optional for open source),"format":"same|png|jpg|psd|tiff|…"="same","naming":string? (tokens: {name}/{NAME}/{Name}, {serial}/{serial:1..4}, {letter}/{LETTER}, {date} and date formats, {ext}/{EXT}; the naming template determines the whole filename),"startingSerial":1..4294967295=1,"stopOnError":bool=false,"errorLog":path? (blank disables it),"quality":0..12?,"calledActions":[{"name","steps"}…]?} → {files, errors, stopped?, skipped?, errorLog?, documents?} (folder batches report per-file job progress and support cancellation)"##,
             native,
             batch
         ),

From 9e718d77934d841ffe623501a4146de08979a18c Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Mon, 2 Nov 2026 14:10:42 -0800
Subject: [PATCH 071/109] Actions: Check Spelling playback keeps to its
 document and its corrections run

- A loaded spellCheck step reads null and Usng by name, in either order.
- A correction step (action set) with its dialog on runs without opening
  the Check Spelling dialog.
- Done continues a waiting action only on the document it was playing on;
  on another document the action ends there and the status says why.
- When recording the step fails at Done, the status keeps that error next
  to the playback's outcome.
---
 crates/engine/src/cmd/atn_cmds/events.rs    |  6 +-
 crates/engine/src/cmd/atn_cmds/tests.rs     | 19 +++++-
 crates/ui-egui/src/panels/actions.rs        | 28 +++++++-
 crates/ui-egui/src/panels/actions/tests.rs  | 75 +++++++++++++++++++++
 crates/ui-egui/src/panels/type_panels_ui.rs | 15 +++--
 5 files changed, 132 insertions(+), 11 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/events.rs b/crates/engine/src/cmd/atn_cmds/events.rs
index 1194ebbbc7..2dbad14d90 100644
--- a/crates/engine/src/cmd/atn_cmds/events.rs
+++ b/crates/engine/src/cmd/atn_cmds/events.rs
@@ -204,10 +204,10 @@ fn spell_check_from(d: &Descriptor) -> Mapped {
         }
         _ => false,
     };
-    let keys: Vec<String> = d.items.iter().map(|(k, _)| trimmed(k)).collect();
+    // Two keys, read by name: `null` and `Usng` in either order, each once.
     let using = get_obj(d, "Usng").filter(|u| u.class_id.is("spellCheck") && u.items.len() == 1);
-    match (keys.as_slice(), get_ref(d, "null"), using.and_then(|u| get_bool(u, "checkAll"))) {
-        ([null, usng], Some(r), Some(all)) if null == "null" && usng == "Usng" && same_ref(r) => step("edit.checkSpelling", json!({"allLayers": all})),
+    match (d.items.len(), get_ref(d, "null"), using.and_then(|u| get_bool(u, "checkAll"))) {
+        (2, Some(r), Some(all)) if same_ref(r) => step("edit.checkSpelling", json!({"allLayers": all})),
         _ => Mapped::Unsupported { harmless: false },
     }
 }
diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index fff810dbc9..12f4405e50 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -5868,7 +5868,9 @@ fn other_check_spelling_forms_stay_kept_steps_and_corrections_are_not_saved() {
     other_class.items[1].1 = D::Descriptor(desc("findReplace").with("checkAll", D::Boolean(true)));
     let mut more_using = spell_check(true);
     more_using.items[1].1 = D::Descriptor(desc("spellCheck").with("checkAll", D::Boolean(true)).with("Fwd ", D::Boolean(true)));
-    for d in [extra, other_target, other_class, more_using, desc("null")] {
+    let mut twice = spell_check(true);
+    twice.items[1] = twice.items[0].clone();
+    for d in [extra, other_target, other_class, more_using, twice, desc("null")] {
         assert!(matches!((event.from)(&d), Mapped::Unsupported { harmless: false }), "{d:?}");
     }
     for params in [
@@ -5881,6 +5883,21 @@ fn other_check_spelling_forms_stay_kept_steps_and_corrections_are_not_saved() {
     }
 }
 
+/// Check Spelling's `null` and `Usng` are read by name: a step that holds them in the other
+/// order loads as the same step.
+#[test]
+fn check_spelling_reads_its_keys_in_either_order() {
+    let event = event_for(&AtnEvent::name("spellCheck")).unwrap();
+    for all in [true, false] {
+        let mut reversed = spell_check(all);
+        reversed.items.reverse();
+        match (event.from)(&reversed) {
+            Mapped::Steps(steps) => assert_eq!(steps, [("edit.checkSpelling".to_string(), json!({"allLayers": all}))]),
+            Mapped::Unsupported { .. } => panic!("Usng before null was kept: {reversed:?}"),
+        }
+    }
+}
+
 /// A setting recorded twice (`Wdth`, `Fade`, `Scl `, a gallery key) would play one value and
 /// save one, dropping the other: such a step stays a Photoshop step (CodeRabbit on #10776).
 #[test]
diff --git a/crates/ui-egui/src/panels/actions.rs b/crates/ui-egui/src/panels/actions.rs
index 59f1102592..9bd77be93c 100644
--- a/crates/ui-egui/src/panels/actions.rs
+++ b/crates/ui-egui/src/panels/actions.rs
@@ -255,7 +255,8 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
         }
         // Check Spelling's dialog opens with Check All Layers as recorded; Done continues the action.
         // While another action waits at the open dialog, this step fails and the waiting one keeps it.
-        if action.dialogs.contains(&i) && !app.automation_input && id == "edit.checkSpelling" {
+        // A correction (`action` set) opens no dialog and runs below.
+        if action.dialogs.contains(&i) && !app.automation_input && id == "edit.checkSpelling" && p.get("action").is_none() {
             if app.ui.type_panels.spell.as_ref().is_some_and(|d| d.resume.is_some()) {
                 failed = Some(json!({"step": i, "id": id, "error": "Check Spelling is already open for another action"}));
                 break;
@@ -265,6 +266,9 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
                 break;
             }
             let token = app.paused_playbacks.pause(action.name.clone(), i + 1, app.session.authorize);
+            if let Some(entry) = app.paused_playbacks.paused.get_mut(&token) {
+                entry.doc = app.session.active().map(|d| d.doc.id);
+            }
             if let Some(d) = app.ui.type_panels.spell.as_mut() {
                 d.resume = Some(token);
             }
@@ -823,6 +827,9 @@ pub(crate) struct PausedPlayback {
     /// The steps that Play ran before this pause (earlier actions of the set, and this one's
     /// steps before the dialog), so the final count covers the whole Play.
     ran: u64,
+    /// The document a pause at Check Spelling was playing on. That dialog doesn't block the
+    /// document tabs, so Done ([`resume_spelling`]) continues only on this document.
+    doc: Option<photocraft_doc::DocId>,
 }
 
 /// The paused playbacks, by the token their dialog carries. The dialog's fields hold only the
@@ -836,7 +843,7 @@ pub(crate) struct PausedPlaybacks {
 impl PausedPlaybacks {
     fn pause(&mut self, action: String, from: usize, gate: Option<Gate>) -> u64 {
         self.last = self.last.wrapping_add(1);
-        self.paused.insert(self.last, PausedPlayback { action, from, gate, record: None, then: Vec::new(), ran: 0 });
+        self.paused.insert(self.last, PausedPlayback { action, from, gate, record: None, then: Vec::new(), ran: 0, doc: None });
         self.last
     }
 
@@ -845,6 +852,23 @@ impl PausedPlaybacks {
     }
 }
 
+/// Check Spelling's Done for the action paused at its step: the action continues when the document
+/// it was playing on is still the active one, and otherwise ends there with the reason in the
+/// status bar. Returns `Ok` when nothing failed.
+pub(crate) fn resume_spelling(app: &mut PhotocraftApp, token: u64) -> Result<(), String> {
+    let fields = serde_json::Map::from_iter([(RESUME.to_string(), json!(token))]);
+    let Some((from, doc)) = app.paused_playbacks.paused.get(&token).map(|p| (p.from, p.doc)) else {
+        return resume(app, &fields);
+    };
+    if doc.is_none() || doc == app.session.active().map(|d| d.doc.id) {
+        return resume(app, &fields);
+    }
+    abandoned(app, &fields);
+    let error = "the active document changed while Check Spelling was open";
+    report_play(app, &json!({"failed": {"step": from.saturating_sub(1), "id": "edit.checkSpelling", "error": error}}));
+    Err(error.into())
+}
+
 /// A step dialog confirmed: continue the action after it (`dialogs::confirm` calls this).
 ///
 /// The remaining steps run under the gate the playback paused with, however the dialog was
diff --git a/crates/ui-egui/src/panels/actions/tests.rs b/crates/ui-egui/src/panels/actions/tests.rs
index 78979616fc..4bf8ae4a5b 100644
--- a/crates/ui-egui/src/panels/actions/tests.rs
+++ b/crates/ui-egui/src/panels/actions/tests.rs
@@ -1541,6 +1541,81 @@ fn a_check_spelling_step_with_its_dialog_opens_it_and_done_continues() {
     assert_eq!(texts, ["Teh cat"]);
 }
 
+/// A correction step (`action` set) runs as it did before the dialog toggle applied to Check
+/// Spelling: its dialog switch opens nothing.
+#[test]
+fn a_check_spelling_correction_with_its_dialog_on_runs_without_opening_it() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let change = json!({"action": "change", "start": 0, "end": 3, "word": "Teh", "replace": "The"});
+    let mut a = Action::new("Fix", vec![("edit.checkSpelling".into(), change), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    let v = play(&mut app, &json!({"action": "Fix"})).unwrap();
+    assert_eq!(v["ran"], 2, "{v}");
+    assert!(app.ui.type_panels.spell.is_none(), "no dialog opened");
+    let st = app.session.active().unwrap();
+    let texts: Vec<String> = st
+        .doc
+        .walk()
+        .into_iter()
+        .filter_map(|(_, _, l)| match &l.content {
+            photocraft_doc::LayerContent::Text(t) => Some(t.text.clone()),
+            _ => None,
+        })
+        .collect();
+    assert_eq!(texts, ["The cat"]);
+}
+
+/// Done after another document became active ends the waiting action there: its remaining steps
+/// don't run on the other document.
+#[test]
+fn check_spelling_done_on_another_document_ends_the_waiting_action() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let mut a = Action::new("Spell", vec![("edit.checkSpelling".into(), json!({"allLayers": false})), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["paused"]["dialog"], crate::type_panels_ui::SPELLING, "{v}");
+    app.run("file.new", json!({"width": 64, "height": 64})).unwrap();
+    crate::type_panels_ui::close_spelling(&mut app);
+    for st in app.session.documents() {
+        assert!(!st.doc.walk().iter().any(|(_, _, l)| l.name == "after"), "a step after the dialog ran");
+    }
+    assert!(app.paused_playbacks.paused.is_empty());
+    assert!(app.ui.status_error, "{}", app.ui.status);
+    assert!(app.ui.status.contains("document"), "{}", app.ui.status);
+}
+
+fn deny_spelling(id: &str, p: &Value) -> photocraft_engine::Result<()> {
+    if id == "edit.checkSpelling" && p.get("action").is_none() { Err(photocraft_engine::EngineError::Other("spelling denied".into())) } else { Ok(()) }
+}
+
+/// Done records the step and continues the waiting action: when recording it fails, the status
+/// keeps that error next to the playback's outcome.
+#[test]
+fn check_spelling_done_keeps_a_recording_error_beside_the_playback_status() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let mut a = Action::new("Spell", vec![("edit.checkSpelling".into(), json!({"allLayers": false})), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["paused"]["dialog"], crate::type_panels_ui::SPELLING, "{v}");
+    app.run("actions.record", json!({"name": "Rec"})).unwrap();
+    app.session.authorize = Some(deny_spelling);
+    crate::type_panels_ui::close_spelling(&mut app);
+    app.session.authorize = None;
+    assert!(layer_names(&app).contains(&"after".to_string()), "Done played the rest");
+    assert!(app.ui.status_error, "{}", app.ui.status);
+    assert!(app.ui.status.contains("spelling denied"), "{}", app.ui.status);
+    assert!(app.ui.status.contains("Played"), "{}", app.ui.status);
+}
+
 #[test]
 fn check_spelling_opened_again_while_an_action_waits_keeps_its_continuation() {
     let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
diff --git a/crates/ui-egui/src/panels/type_panels_ui.rs b/crates/ui-egui/src/panels/type_panels_ui.rs
index 704b96b7dd..0a58ee8542 100644
--- a/crates/ui-egui/src/panels/type_panels_ui.rs
+++ b/crates/ui-egui/src/panels/type_panels_ui.rs
@@ -785,15 +785,20 @@ pub fn open_spelling(app: &mut PhotocraftApp, all_layers: bool) -> Result<Value,
 }
 
 /// Done: an action being recorded gets one Check Spelling step with Check All Layers as the dialog
-/// has it, and an action paused at a Check Spelling step continues.
+/// has it, and an action paused at a Check Spelling step continues on the document it was playing
+/// on. When recording the step fails, the status keeps that error with the playback's outcome.
 pub fn close_spelling(app: &mut PhotocraftApp) {
     let Some(d) = app.ui.type_panels.spell.take() else { return };
-    if app.session.actions.recording.is_some() {
-        let _ = run(app, "edit.checkSpelling", json!({ "allLayers": d.all_layers }));
+    let mut recording_error = None;
+    if app.session.actions.recording.is_some() && run(app, "edit.checkSpelling", json!({ "allLayers": d.all_layers })).is_none() {
+        recording_error = Some(app.ui.status.clone());
     }
     if let Some(token) = d.resume {
-        let fields = serde_json::Map::from_iter([(crate::actions::RESUME.to_string(), json!(token))]);
-        let _ = crate::actions::resume(app, &fields);
+        let _ = crate::actions::resume_spelling(app, token);
+        if let Some(error) = recording_error {
+            app.ui.status = format!("{error} ({})", app.ui.status);
+            app.ui.status_error = true;
+        }
     }
 }
 

From 6dd5156e5f71e4fdad66de1e54e45f2b2c009e5f Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Mon, 2 Nov 2026 23:21:59 +0100
Subject: [PATCH 072/109] Crop: the Shift-corner unit test expects the diagonal
 size (#10871)

---
 crates/ui-egui/src/tools/crop_ui/tests.rs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/crates/ui-egui/src/tools/crop_ui/tests.rs b/crates/ui-egui/src/tools/crop_ui/tests.rs
index 6fba4e57d4..65b35c689a 100644
--- a/crates/ui-egui/src/tools/crop_ui/tests.rs
+++ b/crates/ui-egui/src/tools/crop_ui/tests.rs
@@ -387,13 +387,14 @@ fn handles_resize_with_shift_and_alt() {
     // Bottom-right corner, free.
     drag(&mut app, &[[120.0, 60.0], [140.0, 70.0]], NONE);
     assert_eq!(app.ui.crop_rect, Some([20.0, 20.0, 140.0, 70.0]));
-    // ⇧ keeps 120:50 from the top-left corner: the larger relative extent wins.
+    // ⇧ keeps 120:50 from the top-left corner: the corner follows the frame's diagonal, so the
+    // drag (−10, −20) projected onto (−120, −50) grows the frame by 2200 / 16900 (#10871).
     app.ui.crop_rect = Some([20.0, 20.0, 140.0, 70.0]);
     drag(&mut app, &[[20.0, 20.0], [10.0, 0.0]], SHIFT);
     let r = app.ui.crop_rect.unwrap();
     assert_eq!((r[2], r[3]), (140.0, 70.0), "opposite corner fixed");
     assert!(((r[2] - r[0]) / (r[3] - r[1]) - 120.0 / 50.0).abs() < 1e-9, "{r:?}");
-    assert_eq!(r[3] - r[1], 70.0);
+    assert!((r[3] - r[1] - 50.0 * (1.0 + 2200.0 / 16900.0)).abs() < 1e-9, "{r:?}");
     // ⌥ resizes about the centre.
     app.ui.crop_rect = Some([40.0, 20.0, 80.0, 60.0]);
     drag(&mut app, &[[80.0, 40.0], [90.0, 40.0]], Modifiers::ALT);

From bc48f31da07531f44abba6ca9168481a5ee521b6 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 16:43:52 -0600
Subject: [PATCH 073/109] Allow ATN group-end select no-op through admission

---
 crates/engine/src/session/execute.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/crates/engine/src/session/execute.rs b/crates/engine/src/session/execute.rs
index 4b2a4b4a50..239fa2124f 100644
--- a/crates/engine/src/session/execute.rs
+++ b/crates/engine/src/session/execute.rs
@@ -181,6 +181,15 @@ impl Session {
         if !spec.params.contains("\"layer\":id") {
             return Ok(None);
         }
+        // An ATN group-end index is a valid no-op only for Select. Let that command validate
+        // its other parameters and preserve the current selection.
+        if spec.id == "layer.select"
+            && let Some(selector @ Value::Object(fields)) = params.get("layer")
+            && (fields.contains_key("index") || fields.contains_key("ordinal"))
+            && commands::recorded_layer(self, selector)?.is_none()
+        {
+            return Ok(None);
+        }
         let target = match commands::explicit_layer(self, params) {
             Ok(Some(target)) => target,
             Ok(None) => return Ok(None),

From c0b08120a6212ee63aed09ac878a1b4fe932b568 Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Tue, 3 Nov 2026 00:32:25 +0100
Subject: [PATCH 074/109] Reveal All's crop passes the session gate; Crop doc
 names the Content-Aware exception (#10867)

Reveal All runs its crop through crop_keeping_background instead of
Session::execute, so the session's authorize gate no longer saw the
image.crop it runs on its behalf. It now calls the gate with the crop's
params before the crop, as dispatch would.

The image.crop params doc now says the Background becomes Layer 0 with
Delete Cropped Pixels off only when contentAware is false.

Tests: the action-step case now goes through a binary .atn (the Crop
descriptor carries Dlt false, import decodes it, actions.play runs it);
new tests for the Reveal All gate and for Content-Aware with Delete off
keeping the Background.
---
 crates/engine/src/cmd/extra_cmds.rs           |  5 ++
 crates/engine/src/cmd/image_cmds.rs           |  2 +-
 .../tests/it/crop_delete_off_background.rs    | 80 ++++++++++++++++---
 3 files changed, 75 insertions(+), 12 deletions(-)

diff --git a/crates/engine/src/cmd/extra_cmds.rs b/crates/engine/src/cmd/extra_cmds.rs
index f83d93bc00..093a8af370 100644
--- a/crates/engine/src/cmd/extra_cmds.rs
+++ b/crates/engine/src/cmd/extra_cmds.rs
@@ -880,6 +880,11 @@ pub fn specs() -> Vec<CommandSpec> {
             // One History step named as in Photoshop, not the crop's "Crop". The Background stays a
             // Background, unlike a Crop tool crop with Delete Cropped Pixels off (#10867).
             let p = json!({"x": all.x0, "y": all.y0, "width": all.width(), "height": all.height(), "deleteCroppedPixels": false});
+            // The crop runs without `Session::execute`, so it passes the session's gate here, as a
+            // command run on Reveal All's behalf would.
+            if let Some(gate) = s.authorize {
+                gate("image.crop", &p)?;
+            }
             crate::analysis_cmds::compound(s, "Reveal All", |s| crate::image_cmds::crop_keeping_background(s, &p))?;
             Ok(json!({"changed": true}))
         }),
diff --git a/crates/engine/src/cmd/image_cmds.rs b/crates/engine/src/cmd/image_cmds.rs
index f87fb91709..e3acc2b801 100644
--- a/crates/engine/src/cmd/image_cmds.rs
+++ b/crates/engine/src/cmd/image_cmds.rs
@@ -1032,7 +1032,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "image.crop",
             "Crop",
             ["Image"],
-            r##"{"x":px,"y":px,"width":px,"height":px,"angle":-3600..3600=0,"deleteCroppedPixels":bool=true,"contentAware":bool=false,"targetWidth":px,"targetHeight":px,"resolution":ppi,"resample":"bicubic|bilinear|nearest|lanczos|preserveDetails"="bicubic"} → {x,y,width,height,documentWidth,documentHeight,resolution} (targetWidth/targetHeight, both or neither: the cropped area is resampled to exactly that size, as Image Size, in the same undo step; resolution: the document's new ppi; deleteCroppedPixels false: the pixels past the frame are kept and the Background becomes a normal layer, "Layer 0", so an extension is transparent on every layer; contentAware: the Crop tool's Fill › Content-Aware Fill, the area a rotated or extending crop uncovers filled from its surroundings on the Background, else the active pixel layer)"##,
+            r##"{"x":px,"y":px,"width":px,"height":px,"angle":-3600..3600=0,"deleteCroppedPixels":bool=true,"contentAware":bool=false,"targetWidth":px,"targetHeight":px,"resolution":ppi,"resample":"bicubic|bilinear|nearest|lanczos|preserveDetails"="bicubic"} → {x,y,width,height,documentWidth,documentHeight,resolution} (targetWidth/targetHeight, both or neither: the cropped area is resampled to exactly that size, as Image Size, in the same undo step; resolution: the document's new ppi; deleteCroppedPixels false: the pixels past the frame are kept and, unless contentAware, the Background becomes a normal layer, "Layer 0", so an extension is transparent on every layer (with contentAware the Background stays); contentAware: the Crop tool's Fill › Content-Aware Fill, the area a rotated or extending crop uncovers filled from its surroundings on the Background, else the active pixel layer)"##,
             has_doc,
             crop
         ),
diff --git a/crates/engine/tests/it/crop_delete_off_background.rs b/crates/engine/tests/it/crop_delete_off_background.rs
index bccb37e136..96350d4a1c 100644
--- a/crates/engine/tests/it/crop_delete_off_background.rs
+++ b/crates/engine/tests/it/crop_delete_off_background.rs
@@ -2,8 +2,10 @@
 //! Photoshop does: it keeps the pixels past the canvas, and an extension is transparent on every
 //! layer. Delete on keeps the Background, and Image › Reveal All is unchanged (#10867).
 
-use photocraft_engine::Session;
+use photocraft_engine::actions_cmds::Action;
+use photocraft_engine::{EngineError, Session, atn_cmds};
 use photocraft_geom::Rect;
+use photocraft_psd::{atn, descriptor::Value as D};
 use serde_json::{Value, json};
 
 const MAGENTA: [f32; 4] = [1.0, 0.0, 1.0, 1.0];
@@ -106,13 +108,41 @@ fn a_turned_crop_turns_layer_0_with_the_others() {
 
 #[test]
 fn the_action_steps_turned_crop_unlocks_the_background() {
-    // The action step `Crop` with `Dlt` false, rect (100,100)–(700,400) and angle 10°, scaled down.
+    // The action step `Crop` with `Dlt` false, rect (100,100)–(700,400) and angle 10°, scaled down,
+    // through a binary .atn: its descriptor carries `Dlt` false, the importer decodes it and
+    // `actions.play` runs the step.
+    let params = json!({"x": 10, "y": 10, "width": 60, "height": 30, "angle": 10, "deleteCroppedPixels": false});
+    let action = Action::new("Crop", vec![("image.crop".into(), params)]);
+    let (bytes, skipped) = atn_cmds::export("Crop", &[&action], &[], false).unwrap();
+    assert!(skipped.is_empty());
+    let file = atn::parse(&bytes).unwrap();
+    let descriptor = file.actions[0].items[0].descriptor.as_ref().unwrap();
+    assert_eq!(descriptor.get("Dlt "), Some(&D::Boolean(false)));
+    let imported = atn_cmds::import(&bytes).unwrap();
+    assert!(imported.unsupported.is_empty() && imported.warnings.is_empty());
+    let step = &imported.actions[0].steps[0];
+    assert_eq!((step.0.as_str(), &step.1["deleteCroppedPixels"]), ("image.crop", &json!(false)));
+
     let mut s = doc();
-    crop(&mut s, json!({"x": 10, "y": 10, "width": 60, "height": 30, "angle": 10}), false);
+    s.actions.list = imported.actions;
+    let before = past(&s);
+    s.execute("actions.play", json!({"action": "Crop"})).unwrap();
+    assert_eq!(past(&s), before + 1, "one undo step");
     assert_eq!(size(&s), (60, 30));
     assert_layer_0(&s, "action step");
 }
 
+#[test]
+fn content_aware_with_delete_off_keeps_the_background() {
+    // Not measured in the reference: the Background stays, and the fill goes on it, as before.
+    let mut s = doc();
+    let mut p = json!({"x": 0, "y": 0, "width": 90, "height": 50, "contentAware": true});
+    p["deleteCroppedPixels"] = json!(false);
+    s.execute("image.crop", p).unwrap();
+    assert_eq!(size(&s), (90, 50));
+    assert_eq!(d(&s).background().map(|l| l.name.as_str()), Some("Background"));
+}
+
 #[test]
 fn a_target_size_crop_unlocks_the_background() {
     let mut s = doc();
@@ -162,14 +192,7 @@ fn undo_restores_the_background() {
 
 #[test]
 fn reveal_all_keeps_the_background() {
-    let mut s = doc();
-    // Quads reaches 10 px past the right edge.
-    s.edit("paint past the canvas", |doc, _| {
-        let quads = doc.layers.last_mut().unwrap();
-        quads.surface_mut().unwrap().fill_rect(Rect::new(80, 0, 90, 50), &RED);
-        Ok(())
-    })
-    .unwrap();
+    let mut s = revealable();
     let before = past(&s);
     s.execute("image.revealAll", json!({})).unwrap();
     assert_eq!(past(&s), before + 1);
@@ -179,6 +202,41 @@ fn reveal_all_keeps_the_background() {
     assert_eq!(bg.surface().unwrap().rgba(85, 25), MAGENTA, "the extension takes the background colour, as before");
 }
 
+/// `doc()` with Quads reaching 10 px past the right edge, so Reveal All has something to reveal.
+fn revealable() -> Session {
+    let mut s = doc();
+    s.edit("paint past the canvas", |doc, _| {
+        let quads = doc.layers.last_mut().unwrap();
+        quads.surface_mut().unwrap().fill_rect(Rect::new(80, 0, 90, 50), &RED);
+        Ok(())
+    })
+    .unwrap();
+    s
+}
+
+#[test]
+fn reveal_alls_crop_passes_the_session_gate() {
+    // A gate that refuses `image.crop` refuses Reveal All's crop too, before anything changes.
+    let mut s = revealable();
+    s.authorize = Some(|id, _| if id == "image.crop" { Err(EngineError::Other("image.crop is not allowed".into())) } else { Ok(()) });
+    let before = past(&s);
+    let err = s.execute("image.revealAll", json!({})).unwrap_err();
+    assert!(err.to_string().contains("image.crop is not allowed"), "{err}");
+    assert_eq!(size(&s), (80, 50));
+    assert_eq!(past(&s), before);
+    assert!(d(&s).background().is_some());
+
+    // A gate that allows it sees the crop Reveal All runs.
+    let mut s = revealable();
+    // (An `Err`, not an assert: the gate runs inside the command's panic guard.)
+    s.authorize = Some(|id, p| {
+        let expected = json!({"x": 0, "y": 0, "width": 90, "height": 50, "deleteCroppedPixels": false});
+        if id == "image.crop" && *p != expected { Err(EngineError::Other(format!("unexpected crop {p}"))) } else { Ok(()) }
+    });
+    s.execute("image.revealAll", json!({})).unwrap();
+    assert_eq!(size(&s), (90, 50));
+}
+
 #[test]
 fn a_document_without_a_background_has_nothing_to_convert() {
     let mut s = Session::new();

From a2c4ac0b0c343a916de262e2be8a8a54b987e882 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 17:36:55 -0600
Subject: [PATCH 075/109] Match Batch Esc flow and show read-only input preview

---
 crates/engine/src/cmd/file_cmds/batch_run.rs |  65 ++++++-
 crates/engine/src/cmd/file_cmds/tests.rs     | 194 +++++++++++++++++++
 crates/engine/src/jobs.rs                    | 165 +++++++++++++++-
 crates/engine/src/jobs/tests.rs              |  33 ++++
 crates/ui-egui/src/canvas/tabs.rs            |   3 +
 crates/ui-egui/src/jobs_ui.rs                |  88 ++++++++-
 crates/ui-egui/src/jobs_ui/tests.rs          |  48 +++++
 docs/atn.md                                  |  13 ++
 docs/gaps.md                                 |  10 +-
 docs/scorecard.md                            |   2 +-
 docs/target-app-parity.md                    |  12 +-
 scorecard/automation.toml                    |   2 +-
 12 files changed, 610 insertions(+), 25 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 0c6e4790c7..c7e393bd1b 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -1,7 +1,7 @@
 use super::open::import_at_raw_ppi;
-use super::paths::{extension, file_name, join, list_images, read_file, stem};
+use super::paths::{extension, file_name, join, list_images, read_file, stem, write_file};
 use super::processing::parse_steps;
-use super::save::{SaveOpts, save_doc, save_doc_as};
+use super::save::{SaveOpts, encode, save_doc, save_doc_as};
 use super::{Arc, Document, EngineError, Result, Session, Value, batch_naming, json, str_param};
 
 /// Inputs of a batch command: `"input"` is a folder or an array of files.
@@ -215,15 +215,25 @@ fn process_one(raw_ppi: f64, path: &str, out: &str, save: SaveOpts, options: Pro
     let mut scratch = Session::new();
     let doc = import_at_raw_ppi(raw_ppi, &file_name(path), &bytes)?;
     scratch.add_document(doc, Some(path.to_string()));
+    if let Some(ctx) = options.ctx {
+        ctx.publish_batch_preview(path, scratch.active().map(|state| state.doc.clone()));
+    }
     let saved_by_action = f(&mut scratch, out)?;
     if let Some(ctx) = options.ctx {
         ctx.check()?;
+        if ctx.batch_interrupt_requested() {
+            return Err(EngineError::Cancelled);
+        }
     }
     if !saved_by_action {
         let d = scratch.active().ok_or(EngineError::NoDocument)?;
         if let Some(format) = options.format {
             let ext = if format == "same" { same_format(path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
-            save_doc_as(&d.doc, out, &ext, save)?;
+            if let Some(ctx) = options.ctx {
+                save_batch_doc(&d.doc, out, &ext, save, ctx)?;
+            } else {
+                save_doc_as(&d.doc, out, &ext, save)?;
+            }
         } else {
             save_doc(&d.doc, out, save)?;
         }
@@ -231,6 +241,15 @@ fn process_one(raw_ppi: f64, path: &str, out: &str, save: SaveOpts, options: Pro
     Ok(())
 }
 
+/// Encode before the Batch write checkpoint. Esc accepted during an action or encode therefore
+/// leaves the current destination untouched; the worker owns the write once the checkpoint passes.
+fn save_batch_doc(doc: &Document, out: &str, format: &str, save: SaveOpts, ctx: &crate::jobs::JobCtx) -> Result<()> {
+    let (bytes, _) = encode(doc, format, save)?;
+    ctx.batch_before_write()?;
+    write_file(out, &bytes)?;
+    Ok(())
+}
+
 #[derive(Clone, Debug)]
 pub(super) struct BatchPolicy {
     pub(super) stop_on_error: bool,
@@ -333,16 +352,36 @@ pub(super) fn process_batch_outputs(
     let mut errors = Vec::new();
     let mut stopped = None;
     let mut done = 0;
+    let mut interrupted = Vec::new();
     for (index, (path, out)) in outputs.iter().enumerate() {
         if ctx.cancelled() {
             break;
         }
+        if ctx.batch_take_interrupt() && !ctx.batch_wait_for_decision() {
+            ctx.publish_batch_preview(path, None);
+            ctx.cancel();
+            break;
+        }
         ctx.progress(index as f32 / total.max(1) as f32, &format!("{} of {total}: {}", index + 1, file_name(path)));
         let result = process_one(raw_ppi, path, out, save, ProcessOptions { format: Some(format), written: None, ctx: Some(ctx) }, f);
         if ctx.cancelled() {
+            ctx.publish_batch_preview(path, None);
             done = index;
             break;
         }
+        if ctx.batch_take_interrupt() {
+            if ctx.batch_wait_for_decision() {
+                ctx.publish_batch_preview(path, None);
+                interrupted.push(path.clone());
+                done = index + 1;
+                continue;
+            }
+            ctx.publish_batch_preview(path, None);
+            ctx.cancel();
+            break;
+        }
+        ctx.batch_after_write();
+        ctx.publish_batch_preview(path, None);
         done = index + 1;
         match result {
             Ok(()) => {
@@ -362,11 +401,14 @@ pub(super) fn process_batch_outputs(
     if !cancelled {
         ctx.progress(1.0, "");
     }
-    let skipped = outputs.iter().skip(done).map(|(path, _)| path.clone()).collect();
-    let mut result = batch_outcome(files, errors, stopped.map(|at| (at, skipped)), policy.error_log.as_deref().filter(|_| log_failure.is_none()));
+    let mut skipped = interrupted;
+    skipped.extend(outputs.iter().skip(done).map(|(path, _)| path.clone()));
+    let mut result = batch_outcome(files, errors, stopped.map(|at| (at, skipped.clone())), policy.error_log.as_deref().filter(|_| log_failure.is_none()));
+    if !skipped.is_empty() {
+        result["skipped"] = json!(skipped);
+    }
     if cancelled {
         result["cancelled"] = json!(true);
-        result["skipped"] = json!(outputs.iter().skip(done).map(|(path, _)| path).collect::<Vec<_>>());
     }
     if let Some(error) = log_failure {
         result["errorLogError"] = json!(error);
@@ -512,10 +554,14 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                 let result = (|| {
                     // A recorded save marks a result. If the action later closes or switches
                     // documents, write the saved snapshot instead of the new active document.
-                    let source = scratch.active().and_then(|state| state.path.as_deref()).unwrap_or("");
-                    let encode_format = if format == "same" { same_format(source) } else { format.trim_start_matches('.').to_ascii_lowercase() };
+                    let source = scratch.active().and_then(|state| state.path.as_deref()).unwrap_or("").to_string();
+                    let encode_format = if format == "same" { same_format(&source) } else { format.trim_start_matches('.').to_ascii_lowercase() };
                     let mut saved: Option<Arc<Document>> = None;
                     for (id, params) in &steps {
+                        ctx.check()?;
+                        if ctx.batch_interrupt_requested() {
+                            return Err(EngineError::Cancelled);
+                        }
                         if batch_save_point(id) {
                             let state = scratch.active_mut().ok_or(EngineError::NoDocument)?;
                             saved = Some(state.doc.clone());
@@ -527,6 +573,7 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                             continue;
                         }
                         let result = scratch.execute(id, params.clone())?;
+                        ctx.publish_batch_preview(&source, scratch.active().map(|state| state.doc.clone()));
                         if let Some(error) = crate::actions_cmds::nested_failure(id, &result) {
                             return Err(EngineError::Other(error));
                         }
@@ -534,7 +581,7 @@ pub(super) fn batch(s: &mut Session, p: &Value) -> Result<Value> {
                     match saved {
                         Some(doc) if scratch.active().is_none_or(|active| active.doc.id != doc.id) => {
                             ctx.check()?;
-                            save_doc_as(&doc, out, &encode_format, save)?;
+                            save_batch_doc(&doc, out, &encode_format, save, ctx)?;
                             Ok(true)
                         }
                         _ => Ok(false),
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index c528c437eb..808150c152 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -89,6 +89,200 @@ fn batch_cancelled_during_an_action_does_not_save_that_input() {
     assert!(!std::path::Path::new(&out).exists());
 }
 
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn batch_interruption_continues_with_the_original_next_output() {
+    use std::sync::mpsc;
+    use std::time::Duration;
+
+    let dir = tmp("batch-interrupt-continue");
+    let first = png(&dir, "first.png", 8, 6, "#ff0000");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let first_out = join(&dir, "out/first_001.png");
+    let second_out = join(&dir, "out/second_002.png");
+    let ctx = crate::jobs::JobCtx::new();
+    let worker_ctx = ctx.clone();
+    let (opened_tx, opened_rx) = mpsc::channel();
+    let (resume_tx, resume_rx) = mpsc::channel();
+    let first_action = std::sync::atomic::AtomicBool::new(true);
+    let worker = std::thread::spawn(move || {
+        let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+        super::batch_run::process_batch_outputs(
+            72.0,
+            vec![(first, first_out.clone()), (second, second_out.clone())],
+            "png",
+            SaveOpts::default(),
+            &policy,
+            &worker_ctx,
+            &|_, _| {
+                if first_action.swap(false, std::sync::atomic::Ordering::AcqRel) {
+                    let _ = opened_tx.send(());
+                    let _ = resume_rx.recv_timeout(Duration::from_secs(10));
+                }
+                Ok(false)
+            },
+        )
+        .map(|result| (result, first_out, second_out))
+    });
+    opened_rx.recv_timeout(Duration::from_secs(10)).unwrap();
+    let preview = ctx.batch_preview().expect("the real opened input is published before its action");
+    assert_eq!(preview.path, join(&dir, "first.png"));
+    assert_eq!((preview.document.size.width, preview.document.size.height), (8, 6));
+    assert!(ctx.request_batch_interrupt(), "Esc is accepted while the first action runs");
+    resume_tx.send(()).unwrap();
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while !ctx.batch_waiting_for_decision() && std::time::Instant::now() < deadline {
+        std::thread::yield_now();
+    }
+    assert!(ctx.batch_waiting_for_decision(), "the worker stopped before writing");
+    assert!(!std::path::Path::new(&join(&dir, "out/first_001.png")).exists());
+    assert!(ctx.decide_batch_interrupt(true));
+    let (result, first_out, second_out) = worker.join().unwrap().unwrap();
+    assert_eq!(result["files"], json!([second_out]), "Continue keeps the original serial: {result}");
+    assert!(!std::path::Path::new(&first_out).exists());
+    assert!(std::path::Path::new(&second_out).exists());
+    assert!(ctx.batch_preview().is_none(), "the preview closes after the last input");
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn batch_stop_after_interruption_preserves_prior_outputs_and_never_saves_current() {
+    use std::sync::mpsc;
+    use std::time::Duration;
+
+    let dir = tmp("batch-interrupt-stop");
+    let first = png(&dir, "first.png", 8, 6, "#ff0000");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let third = png(&dir, "third.png", 8, 6, "#0000ff");
+    let out = join(&dir, "out");
+    let first_out = join(&out, "first.png");
+    let second_out = join(&out, "second.png");
+    let third_out = join(&out, "third.png");
+    let ctx = crate::jobs::JobCtx::new();
+    let worker_ctx = ctx.clone();
+    let (opened_tx, opened_rx) = mpsc::channel();
+    let (resume_tx, resume_rx) = mpsc::channel();
+    let worker = std::thread::spawn(move || {
+        let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+        super::batch_run::process_batch_outputs(
+            72.0,
+            vec![(first, first_out), (second, second_out), (third, third_out)],
+            "png",
+            SaveOpts::default(),
+            &policy,
+            &worker_ctx,
+            &|_, path| {
+                if path.ends_with("second.png") {
+                    let _ = opened_tx.send(());
+                    let _ = resume_rx.recv_timeout(Duration::from_secs(10));
+                }
+                Ok(false)
+            },
+        )
+    });
+    opened_rx.recv_timeout(Duration::from_secs(10)).unwrap();
+    assert!(ctx.request_batch_interrupt());
+    resume_tx.send(()).unwrap();
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while !ctx.batch_waiting_for_decision() && std::time::Instant::now() < deadline {
+        std::thread::yield_now();
+    }
+    assert!(ctx.batch_waiting_for_decision());
+    assert!(ctx.decide_batch_interrupt(false));
+    let result = worker.join().unwrap().unwrap();
+    assert_eq!(result["files"], json!([join(&out, "first.png")]), "{result}");
+    assert_eq!(result["cancelled"], true, "{result}");
+    assert_eq!(result["skipped"], json!([join(&dir, "second.png"), join(&dir, "third.png")]), "{result}");
+    assert!(std::path::Path::new(&join(&out, "first.png")).exists());
+    assert!(!std::path::Path::new(&join(&out, "second.png")).exists());
+    assert!(!std::path::Path::new(&join(&out, "third.png")).exists());
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn batch_continue_keeps_errors_before_and_after_the_interruption_in_one_log() {
+    use std::time::Duration;
+
+    let dir = tmp("batch-interrupt-error-log");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let fourth = png(&dir, "fourth.png", 8, 6, "#0000ff");
+    let before = join(&dir, "missing-before.png");
+    let after = join(&dir, "missing-after.png");
+    let out = join(&dir, "out");
+    let log = join(&dir, "errors.txt");
+    let ctx = crate::jobs::JobCtx::new();
+    let decider_ctx = ctx.clone();
+    let decider = std::thread::spawn(move || {
+        let deadline = std::time::Instant::now() + Duration::from_secs(10);
+        while !decider_ctx.batch_waiting_for_decision() && std::time::Instant::now() < deadline {
+            std::thread::yield_now();
+        }
+        if !decider_ctx.batch_waiting_for_decision() {
+            decider_ctx.cancel();
+            return false;
+        }
+        decider_ctx.decide_batch_interrupt(true)
+    });
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: Some(log.clone()) };
+    let result = super::batch_run::process_batch_outputs(
+        72.0,
+        vec![
+            (before.clone(), join(&out, "missing-before.png")),
+            (second.clone(), join(&out, "second.png")),
+            (after.clone(), join(&out, "missing-after.png")),
+            (fourth, join(&out, "fourth.png")),
+        ],
+        "png",
+        SaveOpts::default(),
+        &policy,
+        &ctx,
+        &|_, path| {
+            if path.ends_with("second.png") {
+                assert!(ctx.request_batch_interrupt());
+            }
+            Ok(false)
+        },
+    )
+    .unwrap();
+    assert!(decider.join().unwrap());
+    assert_eq!(result["errors"].as_array().map(Vec::len), Some(2), "{result}");
+    assert_eq!(result["skipped"], json!([second]), "{result}");
+    assert_eq!(result["files"], json!([join(&out, "fourth.png")]), "{result}");
+    let text = batch_log(&log);
+    assert!(text.contains("missing-before.png") && text.contains("missing-after.png"), "{text}");
+    assert!(!text.contains("second.png"), "a skipped input is not an error: {text}");
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn batch_continue_between_inputs_still_processes_the_next_input() {
+    use std::time::Duration;
+
+    let dir = tmp("batch-interrupt-between-inputs");
+    let input = png(&dir, "next.png", 8, 6, "#ff0000");
+    let output = join(&dir, "out/next.png");
+    let ctx = crate::jobs::JobCtx::new();
+    assert!(ctx.request_batch_interrupt());
+    let decider_ctx = ctx.clone();
+    let decider = std::thread::spawn(move || {
+        let deadline = std::time::Instant::now() + Duration::from_secs(10);
+        while !decider_ctx.batch_waiting_for_decision() && std::time::Instant::now() < deadline {
+            std::thread::yield_now();
+        }
+        if !decider_ctx.batch_waiting_for_decision() {
+            decider_ctx.cancel();
+            return false;
+        }
+        decider_ctx.decide_batch_interrupt(true)
+    });
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+    let result =
+        super::batch_run::process_batch_outputs(72.0, vec![(input, output.clone())], "png", SaveOpts::default(), &policy, &ctx, &|_, _| Ok(false)).unwrap();
+    assert!(decider.join().unwrap());
+    assert_eq!(result["files"], json!([output]), "the unopened input is still next: {result}");
+    assert!(result.get("skipped").is_none(), "{result}");
+}
+
 #[test]
 fn batch_error_log_cannot_replace_an_input_or_result() {
     let dir = tmp("batch-error-log-collision");
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index f167deae32..ff22f197e0 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -20,7 +20,7 @@
 
 use std::any::Any;
 use std::sync::atomic::{AtomicU8, AtomicU32, Ordering};
-use std::sync::{Arc, Mutex, PoisonError, Weak};
+use std::sync::{Arc, Condvar, Mutex, PoisonError, Weak};
 
 use photocraft_doc::{DocId, Document, LayerId};
 use photocraft_raster::Interrupt;
@@ -89,6 +89,33 @@ struct Shared {
     /// `fetch_max` keeps progress monotonic even with several reporting threads.
     progress: AtomicU32,
     message: Mutex<String>,
+    batch: Mutex<BatchInterrupt>,
+    batch_decision: Condvar,
+    batch_preview: Mutex<Option<BatchPreview>>,
+    batch_preview_generation: std::sync::atomic::AtomicU64,
+}
+
+/// The current folder Batch input, published as an immutable snapshot for the desktop canvas.
+/// It is never added to the live session and cannot receive commands or saves.
+#[derive(Clone, Debug)]
+pub struct BatchPreview {
+    pub path: String,
+    pub document: Arc<Document>,
+    pub generation: u64,
+}
+
+/// The desktop Batch Esc handshake. The worker alone enters `Waiting` at a pre-save
+/// checkpoint; only the UI supplies a decision. Programmatic cancellation uses the separate
+/// atomic flag above and wakes a waiting worker without asking a question.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+enum BatchInterrupt {
+    #[default]
+    Processing,
+    Requested,
+    Waiting,
+    Continue,
+    Stop,
+    Saving,
 }
 
 const CANCEL_REQUESTED: u8 = 1;
@@ -127,15 +154,122 @@ impl JobCtx {
     /// Ask the job to stop (idempotent).
     pub fn cancel(&self) {
         self.shared.state.fetch_or(CANCEL_REQUESTED, Ordering::AcqRel);
+        let _phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        self.shared.batch_decision.notify_all();
     }
 
     /// Accept a cancellation only while the worker has not finished its result. One atomic state
     /// orders a late cancel against completion, including the interval before the UI polls.
     fn cancel_if_running(&self) -> bool {
-        self.shared
+        let accepted = self
+            .shared
             .state
             .try_update(Ordering::AcqRel, Ordering::Acquire, |state| (state & (CANCEL_REQUESTED | WORK_FINISHED) == 0).then_some(state | CANCEL_REQUESTED))
-            .is_ok()
+            .is_ok();
+        if accepted {
+            let _phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+            self.shared.batch_decision.notify_all();
+        }
+        accepted
+    }
+
+    /// Request the reference application's Esc decision for an interactive Batch. A save that
+    /// passed its final write checkpoint cannot be interrupted; the caller may try the next
+    /// input. This does not affect the direct `jobs.cancel` automation API.
+    pub fn request_batch_interrupt(&self) -> bool {
+        if self.cancelled() || self.shared.state.load(Ordering::Acquire) & WORK_FINISHED != 0 {
+            return false;
+        }
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        if *phase != BatchInterrupt::Processing {
+            return false;
+        }
+        *phase = BatchInterrupt::Requested;
+        true
+    }
+
+    /// The worker has stopped before writing the current input and awaits Continue or Stop.
+    pub fn batch_waiting_for_decision(&self) -> bool {
+        *self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) == BatchInterrupt::Waiting
+    }
+
+    /// Answer a waiting interactive Batch question. `continue_next` skips the current input.
+    pub fn decide_batch_interrupt(&self, continue_next: bool) -> bool {
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        if *phase != BatchInterrupt::Waiting {
+            return false;
+        }
+        *phase = if continue_next { BatchInterrupt::Continue } else { BatchInterrupt::Stop };
+        self.shared.batch_decision.notify_all();
+        true
+    }
+
+    /// Whether an action should stop before its next step because Esc was requested.
+    pub fn batch_interrupt_requested(&self) -> bool {
+        *self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) == BatchInterrupt::Requested
+    }
+
+    /// Move an accepted Esc request to the question at a worker checkpoint.
+    pub fn batch_take_interrupt(&self) -> bool {
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        if *phase != BatchInterrupt::Requested {
+            return *phase == BatchInterrupt::Waiting;
+        }
+        *phase = BatchInterrupt::Waiting;
+        true
+    }
+
+    /// Wait for the UI decision without polling. Closing the session or `jobs.cancel` wakes this
+    /// worker; the caller then reports its partial result.
+    pub fn batch_wait_for_decision(&self) -> bool {
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        while *phase == BatchInterrupt::Waiting && !self.cancelled() {
+            phase = self.shared.batch_decision.wait(phase).unwrap_or_else(PoisonError::into_inner);
+        }
+        let continue_next = *phase == BatchInterrupt::Continue && !self.cancelled();
+        *phase = BatchInterrupt::Processing;
+        continue_next
+    }
+
+    /// Mark the start of an input's output write. The same lock orders Esc against this
+    /// checkpoint: a requested interruption never writes that input.
+    pub(crate) fn batch_before_write(&self) -> Result<()> {
+        self.check()?;
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        if *phase == BatchInterrupt::Requested {
+            *phase = BatchInterrupt::Waiting;
+            return Err(EngineError::Cancelled);
+        }
+        if self.cancelled() {
+            return Err(EngineError::Cancelled);
+        }
+        *phase = BatchInterrupt::Saving;
+        Ok(())
+    }
+
+    /// A completed write allows Esc on the next input.
+    pub(crate) fn batch_after_write(&self) {
+        let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
+        if *phase == BatchInterrupt::Saving {
+            *phase = BatchInterrupt::Processing;
+        }
+    }
+
+    /// Publish the current input's document after it opens or an action step changes it.
+    pub fn publish_batch_preview(&self, path: &str, document: Option<Arc<Document>>) {
+        let mut preview = self.shared.batch_preview.lock().unwrap_or_else(PoisonError::into_inner);
+        if preview.as_ref().zip(document.as_ref()).is_some_and(|(shown, next)| shown.path == path && Arc::ptr_eq(&shown.document, next))
+            || (preview.is_none() && document.is_none())
+        {
+            return;
+        }
+        let generation = self.shared.batch_preview_generation.fetch_add(1, Ordering::AcqRel).wrapping_add(1);
+        *preview = document.map(|document| BatchPreview { path: path.to_string(), document, generation });
+    }
+
+    /// A snapshot for rendering, if the current input still has a document open.
+    pub fn batch_preview(&self) -> Option<BatchPreview> {
+        self.shared.batch_preview.lock().unwrap_or_else(PoisonError::into_inner).clone()
     }
 
     #[cfg(not(target_arch = "wasm32"))]
@@ -756,6 +890,31 @@ impl Session {
         true
     }
 
+    /// Ask an interactive Batch worker to stop its current input at the next safe checkpoint.
+    /// Headless clients keep using [`Self::cancel_job`] for a direct partial result.
+    pub fn request_batch_interrupt_job(&self, id: JobId) -> bool {
+        self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").is_some_and(|job| job.ctx.request_batch_interrupt())
+    }
+
+    /// Whether a Batch worker has acknowledged Esc and is waiting for the desktop decision.
+    pub fn batch_interrupt_waiting(&self, id: JobId) -> bool {
+        self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").is_some_and(|job| job.ctx.batch_waiting_for_decision())
+    }
+
+    /// Continue with the next input or stop a Batch paused by the desktop Esc key.
+    pub fn decide_batch_interrupt_job(&self, id: JobId, continue_next: bool) -> bool {
+        self.jobs
+            .running
+            .iter()
+            .find(|job| job.id == id && job.command == "file.automate.batch")
+            .is_some_and(|job| job.ctx.decide_batch_interrupt(continue_next))
+    }
+
+    /// The current read-only folder Batch document shown by the desktop while work runs.
+    pub fn batch_preview(&self, id: JobId) -> Option<BatchPreview> {
+        self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").and_then(|job| job.ctx.batch_preview())
+    }
+
     /// Cancel every running job (e.g. before quitting).
     pub fn cancel_all_jobs(&mut self) {
         let ids: Vec<JobId> = self.jobs.running.iter().map(|r| r.id).collect();
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index 4249c809ac..cda760186d 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -573,6 +573,39 @@ fn cancelled_batch_job_returns_its_partial_result() {
     assert!(matches!(s.wait_job(id), Err(EngineError::Cancelled)));
 }
 
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn programmatic_cancel_wakes_a_batch_waiting_for_the_desktop_decision() {
+    let mut s = Session::new();
+    let id = job(s
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            |ctx| {
+                while !ctx.batch_take_interrupt() {
+                    ctx.check()?;
+                    std::thread::yield_now();
+                }
+                let continued = ctx.batch_wait_for_decision();
+                Ok(json!({"continued": continued, "files": [], "cancelled": ctx.cancelled()}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap());
+    assert!(s.request_batch_interrupt_job(id));
+    let deadline = Instant::now() + Duration::from_secs(10);
+    while !s.batch_interrupt_waiting(id) && Instant::now() < deadline {
+        std::thread::yield_now();
+    }
+    assert!(s.batch_interrupt_waiting(id));
+    assert!(s.cancel_job(id), "jobs.cancel remains direct and wakes the worker");
+    let JobOutcome::Done(result) = wait_event(&mut s, id).outcome else { panic!("batch partial result was lost") };
+    assert_eq!(result["continued"], false);
+    assert_eq!(result["cancelled"], true);
+}
+
 #[test]
 fn accepted_batch_cancellation_after_result_snapshot_is_reported() {
     let mut s = Session::new();
diff --git a/crates/ui-egui/src/canvas/tabs.rs b/crates/ui-egui/src/canvas/tabs.rs
index 2ab777b532..5643d2c45f 100644
--- a/crates/ui-egui/src/canvas/tabs.rs
+++ b/crates/ui-egui/src/canvas/tabs.rs
@@ -5,6 +5,9 @@ use super::{Color32, PhotocraftApp, Pos2, Rect, Sense, Stroke, TextureOptions, c
 /// Tabs + canvas for the active document, or the start screen; then drops layers dragged onto
 /// another document (`layer_transfer`).
 pub fn document_area(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
+    if crate::jobs_ui::batch_preview(app, ui) {
+        return;
+    }
     crate::distort_ui::drop_foreign(app);
     documents(app, ui);
     crate::layer_transfer::finish(app, ui.ctx());
diff --git a/crates/ui-egui/src/jobs_ui.rs b/crates/ui-egui/src/jobs_ui.rs
index bdc641468e..b1ad5d8b73 100644
--- a/crates/ui-egui/src/jobs_ui.rs
+++ b/crates/ui-egui/src/jobs_ui.rs
@@ -175,6 +175,8 @@ pub struct JobsUi {
     pub focus: Option<JobId>,
     /// The job the latest [`run`] started (the control channel waits on it).
     pub(crate) last_started: Option<JobId>,
+    /// Cached read-only canvas image of the current folder Batch input.
+    batch_preview_texture: Option<(JobId, u64, egui::TextureHandle)>,
 }
 
 /// Run command `id`: in the background when background jobs are on and the command is a job
@@ -385,7 +387,15 @@ pub fn tick(app: &mut PhotocraftApp, ctx: &egui::Context) {
         && !crate::zoom_field::editing(ctx)
         && ctx.input_mut(|i| i.consume_key(egui::Modifiers::NONE, egui::Key::Escape))
     {
-        cancel(app, job.id);
+        if job.command == "file.automate.batch" {
+            if app.session.batch_interrupt_waiting(job.id) {
+                app.session.decide_batch_interrupt_job(job.id, false);
+            } else {
+                app.session.request_batch_interrupt_job(job.id);
+            }
+        } else {
+            cancel(app, job.id);
+        }
     }
 }
 
@@ -707,6 +717,9 @@ pub fn save_progress(app: &PhotocraftApp, doc: DocId) -> Option<String> {
 /// (the file name on hover). Draws nothing when no job runs.
 pub fn status_progress(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     let Some(j) = job_in_view(app) else { return };
+    if j.command == "file.automate.batch" {
+        return;
+    }
     let saving = app.jobs.saves.iter().any(|s| s.job == j.id);
     let t = Tokens::get(ui.ctx());
     let (bar_w, bar_h) = if t.pro { (120.0, 6.0) } else { (140.0, 6.0) };
@@ -738,17 +751,63 @@ pub fn status_progress(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     }
 }
 
+/// Show the folder Batch worker's immutable current document in the canvas area. The worker
+/// publishes snapshots rather than adding them to `Session`, so no edit or Save can target one.
+pub(crate) fn batch_preview(app: &mut PhotocraftApp, ui: &mut egui::Ui) -> bool {
+    let current = app
+        .session
+        .jobs()
+        .into_iter()
+        .filter(|job| job.command == "file.automate.batch")
+        .find_map(|job| app.session.batch_preview(job.id).map(|preview| (job.id, preview)));
+    let Some((id, preview)) = current else {
+        app.jobs.batch_preview_texture = None;
+        return false;
+    };
+    if !app.jobs.batch_preview_texture.as_ref().is_some_and(|(cached_id, generation, _)| *cached_id == id && *generation == preview.generation) {
+        let image = photocraft_compose::thumbnail(&preview.document, 1024);
+        let pixels = egui::ColorImage::from_rgba_unmultiplied([image.width as usize, image.height as usize], &image.pixels);
+        let texture = ui.ctx().load_texture(format!("batch-preview-{}-{}", id.0, preview.generation), pixels, egui::TextureOptions::LINEAR);
+        app.jobs.batch_preview_texture = Some((id, preview.generation, texture));
+    }
+    let Some((_, _, texture)) = &app.jobs.batch_preview_texture else { return false };
+    let t = Tokens::get(ui.ctx());
+    let name = std::path::Path::new(&preview.path).file_name().map(|name| name.to_string_lossy().into_owned()).unwrap_or_else(|| preview.path.clone());
+    ui.horizontal(|ui| {
+        ui.label(RichText::new(name).color(t.text).font(crate::theme::semibold(12.5)));
+        ui.label(RichText::new(tl!("Batch preview")).color(t.text_faint).size(11.0));
+    });
+    let area = ui.available_rect_before_wrap();
+    ui.allocate_rect(area, Sense::hover());
+    let size = texture.size_vec2();
+    if size.x > 0.0 && size.y > 0.0 {
+        let scale = (area.width() / size.x).min(area.height() / size.y);
+        if !scale.is_finite() {
+            return true;
+        }
+        let scale = scale.clamp(0.0, 1.0);
+        let target = Rect::from_center_size(area.center(), size * scale);
+        ui.painter().rect_filled(target, 0.0, Color32::WHITE);
+        ui.painter().image(texture.id(), target, Rect::from_min_max(egui::Pos2::ZERO, egui::pos2(1.0, 1.0)), Color32::WHITE);
+    }
+    true
+}
+
 /// The modal progress window for a job locking the active document (Photoshop shows one for
 /// long filters): title, status, bar, percentage and elapsed time, Cancel. Appears after
 /// [`DIALOG_DELAY_MS`]; Esc cancels (see [`tick`]). A save shows it only when it runs in the
 /// foreground (Save in Background off), and then at once, so nothing can be clicked meanwhile; a
 /// background save shows its progress in the tab and the status bar instead.
 pub fn dialog(app: &mut PhotocraftApp, ctx: &egui::Context) {
+    if let Some(job) = app.session.jobs().into_iter().find(|job| job.command == "file.automate.batch" && app.session.batch_interrupt_waiting(job.id)) {
+        batch_interrupt_dialog(app, ctx, job.id);
+        return;
+    }
     let j = match foreground_save(app) {
         Some(j) => j,
         None => {
             let Some(j) = app.session.active_job() else { return };
-            if j.elapsed_ms < DIALOG_DELAY_MS || app.jobs.saves.iter().any(|s| s.job == j.id) {
+            if j.command == "file.automate.batch" || j.elapsed_ms < DIALOG_DELAY_MS || app.jobs.saves.iter().any(|s| s.job == j.id) {
                 return;
             }
             j
@@ -788,6 +847,31 @@ pub fn dialog(app: &mut PhotocraftApp, ctx: &egui::Context) {
     }
 }
 
+/// Photoshop's question after Esc interrupts one input. The worker is parked before its save;
+/// Continue advances the same run to the next input, and Stop returns its partial result.
+fn batch_interrupt_dialog(app: &mut PhotocraftApp, ctx: &egui::Context, id: JobId) {
+    let t = Tokens::get(ctx);
+    let mut decision = None;
+    egui::Modal::new(egui::Id::unique("batch-interrupted")).show(ctx, |ui| {
+        ui.set_width(390.0);
+        ui.label(RichText::new(tl!("Batch")).font(crate::theme::semibold(15.0)));
+        ui.add_space(8.0);
+        ui.label(RichText::new(tl!("A command was cancelled or stopped during batch processing. Continue with the next file or stop?")).color(t.text_dim));
+        ui.add_space(14.0);
+        ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
+            if crate::widgets::primary_button(ui, tl!("Continue"), 96.0).clicked() {
+                decision = Some(true);
+            }
+            if crate::widgets::secondary_button(ui, tl!("Stop"), 84.0).clicked() {
+                decision = Some(false);
+            }
+        });
+    });
+    if let Some(continue_next) = decision {
+        app.session.decide_batch_interrupt_job(id, continue_next);
+    }
+}
+
 fn elapsed(ms: f64) -> String {
     let s = (ms / 1000.0).max(0.0);
     if s < 60.0 { format!("{s:.1} s") } else { format!("{}:{:02}", (s / 60.0).floor() as u64, (s % 60.0).floor() as u64) }
diff --git a/crates/ui-egui/src/jobs_ui/tests.rs b/crates/ui-egui/src/jobs_ui/tests.rs
index e33db9df8d..e7e5105796 100644
--- a/crates/ui-egui/src/jobs_ui/tests.rs
+++ b/crates/ui-egui/src/jobs_ui/tests.rs
@@ -798,6 +798,54 @@ fn cancelled_batch_with_partial_results_reports_cancellation_without_beeping() {
     assert_eq!(reply["result"]["files"], json!(["done.png"]));
 }
 
+#[test]
+fn interactive_batch_shows_its_read_only_input_and_asks_after_escape() {
+    let mut h = app_harness();
+    let original = h.state().session.active().unwrap().doc.clone();
+    let (ready_tx, ready_rx) = std::sync::mpsc::channel();
+    let Started::Job(id) = h
+        .state_mut()
+        .session
+        .start_job(
+            "file.automate.batch",
+            json!({}),
+            "Batch",
+            false,
+            move |ctx| {
+                let mut scratch = photocraft_engine::Session::new();
+                scratch.execute("file.new", json!({"name": "input.png", "width": 16, "height": 12, "background": "#00ff00"}))?;
+                ctx.publish_batch_preview("/source/input.png", scratch.active().map(|state| state.doc.clone()));
+                let _ = ready_tx.send(());
+                while !ctx.batch_take_interrupt() {
+                    ctx.check()?;
+                    std::thread::sleep(Duration::from_millis(1));
+                }
+                let continued = ctx.batch_wait_for_decision();
+                ctx.publish_batch_preview("/source/input.png", None);
+                Ok(json!({"continued": continued, "files": []}))
+            },
+            |_, result| Ok(result),
+        )
+        .unwrap()
+    else {
+        panic!("batch did not start as a job")
+    };
+    ready_rx.recv_timeout(Duration::from_secs(10)).unwrap();
+    frames_until(&mut h, 1, |h| h.query_by_label("Batch preview").is_some());
+    assert!(h.query_by_label("input.png").is_some(), "the current input appears in the canvas");
+    assert!(h.query_by_label("Batch").is_none(), "the Batch progress readout is hidden while its input is visible");
+    assert!(Arc::ptr_eq(&original, &h.state().session.active().unwrap().doc), "preview cannot replace the editable document");
+    h.key_press(egui::Key::Escape);
+    frames_until(&mut h, 1, |h| h.query_by_label("Continue").is_some());
+    assert!(h.state().session.batch_interrupt_waiting(id));
+    h.get_by_label("Continue").click();
+    frames_until(&mut h, 1, |h| h.state().session.job(id).is_none());
+    let result = h.state().session.jobs_with_recent().into_iter().find(|job| job.id == id).and_then(|job| job.result).unwrap();
+    assert_eq!(result["continued"], true);
+    assert!(h.query_by_label("Batch preview").is_none(), "the input closes after the decision");
+    assert!(Arc::ptr_eq(&original, &h.state().session.active().unwrap().doc));
+}
+
 #[test]
 fn printing_keeps_drawing_and_reports_only_the_final_spooler_result() {
     for success in [true, false] {
diff --git a/docs/atn.md b/docs/atn.md
index 99f883fc98..26894a6dc7 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -561,6 +561,19 @@ Measured with a folder `in` holding `a.png`, `b.png`, `notes.txt` and `sub/a.png
   during batch processing. Continue with the next file or stop?" (Continue / Stop). Stop ends the batch
   at once; the file being processed is not saved (12 of 60 written in the test). There is no progress
   bar: the documents open and close in the window as they are processed.
+
+Batch cancellation conformance (Photoshop 2026 observation above; PhotoCraft's producer is
+`file_cmds::batch_run::process_batch_outputs`, and its desktop consumer is `jobs_ui::tick`):
+
+| Reference step | Acceptance gate | Status |
+|---|---|---|
+| Plan folder order, names and serials once | Continue retains the original plan and next serial | Implemented and tested; Esc between inputs does not skip the unopened input |
+| Show the opened input while its action runs | A read-only document preview appears in the canvas and closes with the input | Implemented and visually checked; deliberate deviation: worker snapshots are not live tabs or Layers panel targets, so they cannot be edited or saved by mistake |
+| Interrupt the current command on Esc | The current input reaches a checkpoint before any output write | Implemented and tested before save; once the crash-safe atomic write begins, Esc is refused because publication cannot be retracted |
+| Ask Continue or Stop | Continue skips the interrupted input; Stop returns prior outputs and skips the rest | Implemented and tested in engine and UI |
+| Keep headless cancellation direct | `jobs.cancel` returns partial results without an interactive question | Implemented and tested, including a worker waiting for a desktop decision |
+| No progress bar | The desktop Batch preview is the visible feedback | Implemented, UI tested and visually checked |
+| Preserve error policy and log | Continue retains earlier errors and writes one final UTF-16 LE log | Implemented and tested with errors before and after Esc |
 - **Return value:** when any file failed, the Batch step itself reports "cancelled" (the dialog returns no
   descriptor); a script run with Stop For Errors reports success even though it stopped.
 
diff --git a/docs/gaps.md b/docs/gaps.md
index 6e489249d0..77fdc65aef 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -1,6 +1,6 @@
 # Where PhotoCraft falls short of Photoshop
 
-> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-02 · **Change:** minor (G11: Batch measured output naming and UTF-16 log corrections; remaining progress and cancel prompt parity tracked, #4579; G11: Render ATN events mapped; Stylize/Pixelate ATN events mapped, current counts 128 supported/89 unmapped; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-11-02 · **Change:** minor (G11: Batch Esc Continue/Stop and read-only input previews; full live tabs remain open, #4579; G11: Render ATN events mapped; Stylize/Pixelate ATN events mapped, current counts 128 supported/89 unmapped; G9: 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; G11: `.atn` document offsets preserve opening order after tab reordering, #7103; embedded AI/PDF/EPS save-back retains native format with a source-bound SVG display preview; Smooth and Feather command masks cropped to selection bounds plus blur reach; G1: Halftone Pattern Filter Gallery settings survive PSD/PSB saves (#8940); cropped selection morphology and command mask conversion performance evidence added; G6: Art History Brush landed as partial, TOOL-213-20, #1610, so no toolbar tool is missing; G4: five hard-round built-in presets use 5% spacing to remove stacked-tip outlines and reduce pressure-opacity bands, #8842; G9: Crop tool canvas menu, #6561; G2: Content-Aware Scale seam carving 1.65–3.6× faster with unchanged output, P28 row 3.3 → 1.6 s on a 4-core VM, #5236; G9: UI scale presets done, 105–120% steps, #3222; G14: lossy DNG, raw sidecars, Camera Raw Defaults live, Calibration and Auto, CR3 assessed as not clean-room feasible; G8: PSD type on a path opens on its path and saves back into the file's `Txt2`, #7962; G11: a recorded Save As imports with its format and file (`file.saveAs`, `file.saveACopy` for As a Copy) instead of as a plain Save that wrote over the played file, #7102; folder destinations stop playback until #5430; adjustment clipping stays visible in compact Properties, #5231; G9: Color panel modes, ramp and copy commands, the same in every theme, UI-217-17, #6000; G17: Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; G10: `.asl` style libraries landed, #1051; G8: area type (TYPE-218-10); G1: smart objects keep Photoshop's Cylinder warp, #4112; G8: paragraph direction buttons in the Paragraph panel and options bar, TYPE-218-2 partial; G1: 32-bit Hue/Saturation and Colorize as Photoshop does them, Photoshop-oracle floor 190/258, #5781; G11: compound layer properties export as separate Photoshop Set events, rename last, #8304; G11: Batch and droplets take the result at the action's Save step, so actions ending in Save As and Close work; G11: `.atn` steps that switch to another open document import, play and save back, #7103; G14: the Nikon D4 white level follows the sample depth, so 12-bit D4 NEFs no longer open 2.6 stops dark, #5978; G14: a Nikon NEF's Adobe RGB preview is read as Adobe RGB (maker-note ColorSpace 0x001E), #5987; Apply Layer Comp action mapping, #7101; G10: JPEG Options dialog landed, FILE-215-19 partial (no Matte, progressive Scans or size preview); G10: Cineon write; G10: DPX read and write, #1049, Cineon and Amiga IFF read; Classical Object Finder improvement; learned segmentation remains open; G4: named, stateful section locks and visible keyboard focus in Brush Settings; G4: independent Brush Pose tilt-axis overrides, #3825 partial; G4: Transfer Mixer-only controls, #3825 partial; G9: Preferences › File Handling › Save in Background takes effect, #6207, 24 of 169 preferences do nothing; G7: Content-Aware Move previews every selection the command takes, coarse then exact, TOOL-213-4 done, #6680; G4: Pattern Stamp and Background Eraser draw live, TOOL-213-7; G9: Animated Zoom pref read: holding the Zoom tool zooms continuously, #6210, prefs that do nothing 25 of 166; G2: a cancelled 24 MP Gaussian Blur job stops in at most 44 ms, P25 under its 200 ms budget in local runs, baseline not re-run, #6205; G1: generated large-file fixtures, a 4.38 GB PSB opens on Windows through io, FILE-216-2 done, #5107; G9: fill and adjustment layers copy and paste whole, #2344; G1: smart filter masks show on PSD open, Photoshop-oracle floor 188/258; G10: DPX read and write, #1049, Cineon read; G1: CMYK Hue/Saturation and Color Balance keep the black ink; G1: CMYK Posterize on the stored values, psd-tools oracle floor 242/309; G1: CMYK adjustment layers composite on the document's inks, Photoshop-oracle floor 165/258; G1: CMYK Brightness/Contrast on the inks, CMYK Threshold's luma; G1: modern Brightness/Contrast's brightness curve matches Photoshop, Photoshop-oracle floor 151/258; G1: Lab documents composite on their stored L, a, b, Photoshop-oracle floor 152/258; G1: Levels on whole levels at every step, Photoshop-oracle floor 146/258, psd-tools 238/309; G1: 32-bit Brightness/Contrast legacy, Channel Mixer, Photo Filter and Black & White tint unclipped as in Photoshop, Photoshop-oracle floor 149/258; G1: mask feathers blur with their exact variance, psd-tools oracle floor 240/309; G1: Threshold splits on Photoshop's luminosity, psd-tools oracle floor 241/309; G1: pass-through clipping base with an adjustment renders isolated, psd-tools oracle floor 240/309; G1: 16-bit Posterize as Photoshop bins it, psd-tools oracle floor 241/309; G1: Gradient Map driven by the W3C luminosity, Photoshop-oracle floor 147/258; G7: Field Blur's on-canvas pins, #3373; G4: Hue Jitter amount track, #3825 partial; G4: minimum field interaction, #3825 partial; G1: CMYK Invert, Posterize and Threshold on the inks, 16-bit Lab Invert; Photoshop-oracle floor 145/258; G11: `.atn` import maps 112 events: Select and Mask, Filter Gallery Spatter, Ripple, Crystallize, Pattern Fill layers, mask targeting, Step Backward, nudges in points, Bitmap mode; G5: Free Transform H/V skew fields; G9: toolbar tool shortcut editing; refreshed against main: G2, G5, G7, G9, G10, G13, G14, G17 items that landed; G10: DPX read and write, #1049; G4: checkbox-only Brush Settings rows; G11: Load/Save Actions `.atn` landed, AUTO-219-2 partial; G5: hold-a-key spring-loaded tools landed, #2672; G1: #2465 fixed; stale missing-tool rows corrected: Color Replacement, Red Eye and Add/Delete Anchor Point are live tools, so only Art History Brush is missing; no estimate changed; G10: Amiga IFF write; G10: PSD spot channels in Photoshop's polarity, earlier PhotoCraft PSDs keep their ink, #7415 split; G10: TIFF alpha and spot channels written and read as extra samples, FILE-215-7 done, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 Every known shortfall against Photoshop 2026 (27.11.0), one entry each, ranked by user impact
 on the way to beta. This is the work list agents pick from: take the highest-ranked entry that
@@ -114,9 +114,10 @@ what an agent can't finish alone.
 - **Partial 2026-11-02 (#4579):** Batch accepts recursive folders with flat output and
   last-result-wins names, as measured in Photoshop 2026. It also accepts live open documents,
   extended naming components, stop-on-error, UTF-16 LE logs, and job cancellation. The CLI
-  exposes the folder options. AUTO-219-5 remains partial: the UI shows job progress and cancels
-  directly instead of opening Photoshop's Continue/Stop prompt; scratch sessions do not show
-  each input in the window. No readiness percentage or estimate changed.
+  exposes the folder options. The desktop now asks Continue/Stop after Esc, preserves the
+  original output plan and cumulative error log, and shows each folder input as a read-only
+  canvas preview without a progress bar. AUTO-219-5 remains partial because worker inputs are
+  not live tabs with Layers panel content. No readiness percentage or estimate changed.
 - **Done 2026-10-31 (#10604):** all four Render ATN events (Group B) load, play and save with measured defaults, documented clamping and strict export checks. The [event reference](atn.md) now lists 120 supported and 97 unmapped events. Other Actions/scripting gaps remain; no overall readiness percentage or estimate changed.
 - **2026-10-31 evidence (#10608):** Group F selection, paste, Fade, Link, Distribute, pattern and older mask/merge events load, play and save through existing commands. Unsupported settings remain kept; AUTO-219-2 remains partial.
 - **Done 2026-10-31 (#10606):** all twelve Stylize/Pixelate ATN events (Group D) load, play and save with measured defaults, documented clamping and strict export checks. The [event reference](atn.md) now lists 128 supported and 89 unmapped events. Other Actions/scripting gaps remain; no overall readiness percentage or estimate changed.
@@ -433,6 +434,7 @@ what an agent can't finish alone.
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | G11: Batch Esc Continue/Stop, one plan and error log across interruptions, and read-only input previews without a progress bar (#4579); live tab parity remains open, AUTO-219-5 partial; readiness and estimate unchanged |
 | 2026-11-02 | minor | G11: measured Batch output is flat and later results replace earlier ones; naming spells the whole filename; UTF-16 LE logs; current progress and cancellation UI tracked as remaining parity work (#4579); AUTO-219-5 partial; readiness and estimate unchanged |
 | 2026-11-01 | minor | G11: Batch recursion, open-document source, extended naming, stop/error log and folder-job progress/cancel (#4579); AUTO-219-5 done; readiness and estimate unchanged |
 | 2026-10-31 | minor | G11: four Render ATN events mapped; current counts 120 supported/97 unmapped. Other Actions gaps, readiness percentages and estimates unchanged. |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index f5686f16cf..df4f6ffa8f 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -259,7 +259,7 @@ Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). T
 | AUTO-219-2 | Actions panel: step and dialog toggles, reorder, delete a step, Stop, sets, .atn import | done | [#219](https://github.com/storytold/photocraft/issues/219) | 2026-10-12: set folders (collapsible, drag between sets, actions.assignSet), dialog toggle column (playback opens the step's dialog seeded with its values and resumes on OK; actions.dialog), Insert Stop… (actions.insert), step toggles, reorder, delete a step; Load/Save Actions (.atn) in the panel menu, CLI batch and actions.load/save (atn_cmds.rs): 90 Photoshop events map to commands both ways, the rest are kept verbatim and fail at playback by name; step toggles, reorder and delete a step done; Stop steps play (actions.stopMessage) but there is no Insert Stop menu item; sets and dialog toggles are stored and round-trip but the panel neither groups by set nor edits the dialog toggle |
 | AUTO-219-3 | actions.record/stop/play/list commands for agents and the CLI | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions.list/get/record/stop/play/delete in actions_cmds.rs; the panel, CLI and MCP share them. Nested steps pass the session authorize hook. |
 | AUTO-219-4 | Replay tests for crop, filters, selections and styled text on a second document | done | [#219](https://github.com/storytold/photocraft/issues/219) | actions_cmds.rs: a_recorded_edit_run_replays_on_a_second_document records a crop, a Gaussian Blur, a selection fill and faux-bold type on one document and replays all of them onto a second (plus the original layer/select/fill replay) |
-| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | partial | [#219](https://github.com/storytold/photocraft/issues/219) | file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. The UI still shows background progress and cancels immediately instead of showing Photoshop's Continue/Stop prompt; folder processing uses scratch sessions rather than opening each file in the window. |
+| AUTO-219-5 | Batch: subfolders, open documents, naming template, progress/cancel, error log, stop | partial | [#219](https://github.com/storytold/photocraft/issues/219) | file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. Desktop Esc asks Continue/Stop, retaining one plan and error log; a read-only canvas preview shows each scratch-session input without a progress bar. Inputs are not live tabs with Layers panel content, so full window parity remains open. |
 | AUTO-219-6 | Plug-in ABI v2: panel kind, progress/cancel calls, read other layers, Last Filter repeats | missing | [#219](https://github.com/storytold/photocraft/issues/219) | runtime.rs:15 ABI_VERSION = 1; manifest.rs:18 Kind::Filter only |
 | AUTO-219-7 | Local ONNX models behind a flag, managed in Preferences; subject select, background removal | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No ONNX runtime dependency |
 | AUTO-219-8 | xtask check that every panel button routes through a command id | missing | [#219](https://github.com/storytold/photocraft/issues/219) | No such xtask check |
diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md
index 845a698121..3913ec3549 100644
--- a/docs/target-app-parity.md
+++ b/docs/target-app-parity.md
@@ -1,6 +1,6 @@
 # PhotoCraft vs Adobe Photoshop: target-app parity
 
-> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-02 · **Change:** minor (Automation Batch output naming and UTF-16 logs now follow measured Photoshop behavior; progress and cancel prompt remain partial, AUTO-219-5, #4579; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
+> **Last reviewed:** 2026-10-12 · **Last updated:** 2026-11-02 · **Change:** minor (Automation Batch Esc Continue/Stop and read-only input previews now follow the measured cancellation flow; full live tabs remain partial, AUTO-219-5, #4579; 11 of 183 preferences do nothing: startup reads Graphics Adapter through the typed Performance section, so the scorecard audit sees it; selected colour sets edit drawing, tone and supported filters; geometry remains open; Smooth and Feather command masks cropped to selection bounds plus blur reach; cropped selection morphology and command mask conversion performance evidence added; the Camera Raw row names per-camera colour for non-DNG cameras as missing, not the Calibration panel, which landed 2026-10-13; Content-Aware Scale measurements added, #5236; Help › Check for Updates and an opt-out check once per launch, DIST-220-1 partial, #5485; area type, TYPE-218-10 partial, Type scorecard 5 / 5 / 0; compound layer properties export as separate Photoshop Set events, #8304; JPEG Options dialog landed, FILE-215-19 partial; Print › Functions › Bleed through `file.print`; Content-Aware Move live preview for every selection size, TOOL-213-4 done, #6680; retouching evidence: Pattern Stamp and Background Eraser draw live, only the Mixer Brush is left of TOOL-213-7; fill and adjustment layers copy and paste whole, UI-217-23 partial, #2344; shape layers take Density and Feather, TOOL-214-12 done, #5846; on-canvas corner radius widgets, TOOL-214-12; `.atn` import maps 112 events; Free Transform H/V skew fields; stale rows corrected against `main` and the scorecard, estimates unchanged; Photoshop Actions `.atn` load and save; 2026-10-10: Tilt-Shift measurements added; earlier the same day: major, full re-measure against Photoshop 2026 27.11.0; merged `parity-estimate.md` and the roadmap's honest assessment; stale missing-tool rows corrected: Color Replacement and Red Eye are live toolbar tools, Frame landed; percentages unchanged; PSD spot plates in Photoshop's polarity, #7415 split; TIFF spot plates, FILE-215-17's TIFF part, #7415) · **Target:** Adobe Photoshop 2026
 
 The authoritative answer to "how close is PhotoCraft to Photoshop, and how much work is left". The
 one-page summary is [`ROADMAP.md`](../ROADMAP.md); the ranked work list is [`gaps.md`](gaps.md);
@@ -183,10 +183,11 @@ parity for the area and are already contained in the dimension rows above.
 | Workspace, panels, preferences | 40% | 150–250 | 11 of 183 prefs do nothing (scorecard, 2026-11-01); no floating/OS-window panel groups; Libraries, Comments, Contextual Task Bar missing |
 | AI / generative | 10% | 300–600 | See the dimension row |
 
-Batch supports [output naming templates, recursive folders, open documents, per-file progress,
-cancellation, stop-on-error and error logs](batch-naming.md); measured output names and UTF-16
-logs match Photoshop 2026, while the progress display and Continue/Stop cancellation prompt
-remain different. AUTO-219-5 is partial (#4579).
+Batch supports [output naming templates, recursive folders, open documents, Esc Continue/Stop,
+headless cancellation, stop-on-error and error logs](batch-naming.md); measured output names and
+UTF-16 logs match Photoshop 2026. The desktop shows each folder input as a read-only canvas
+snapshot while its action runs, with no progress bar. Full live tabs and Layers panel content for
+those inputs remain different. AUTO-219-5 is partial (#4579).
 
 ## Remaining effort and calibration
 
@@ -588,6 +589,7 @@ See [method, raw measurements and reproduction](five-algorithm-performance.md).
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-11-02 | minor | Automation Batch: Esc Continue/Stop preserves one file plan and error log; a read-only input preview replaces the progress bar; full live tabs remain open, AUTO-219-5 partial (#4579); percentages and estimates unchanged |
 | 2026-11-02 | minor | Automation Batch: flat subfolder output, last-result-wins naming and UTF-16 LE logs matched to measured Photoshop 2026; progress and cancel prompt remain partial, AUTO-219-5 (#4579); percentages and estimates unchanged |
 | 2026-11-01 | minor | Automation Batch: recursive folders, open documents, extended naming, stop/error log and folder-job progress/cancel; AUTO-219-5 done (#4579); percentages and estimates unchanged |
 | 2026-11-01 | minor | UI / UX and Workspace rows: 11 of 183 preferences do nothing (was 12); Graphics Adapter always worked, but startup read it by raw JSON key, which the scorecard audit can't see. Percentages and estimates unchanged |
diff --git a/scorecard/automation.toml b/scorecard/automation.toml
index 89c337903c..311fed18b5 100644
--- a/scorecard/automation.toml
+++ b/scorecard/automation.toml
@@ -44,7 +44,7 @@ id = "AUTO-219-5"
 target = "Batch: subfolders, open documents, naming template, progress/cancel, error log, stop"
 status = "partial"
 issue = 219
-note = "file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. The UI still shows background progress and cancels immediately instead of showing Photoshop's Continue/Stop prompt; folder processing uses scratch sessions rather than opening each file in the window."
+note = "file_cmds/batch_run.rs and batch_naming.rs: flat subfolder output and last-result-wins names measured in Photoshop 2026; live open-document source; file naming components and serials; UTF-16 LE error log; stop-on-error; CLI and Batch dialog, #4579. Desktop Esc asks Continue/Stop, retaining one plan and error log; a read-only canvas preview shows each scratch-session input without a progress bar. Inputs are not live tabs with Layers panel content, so full window parity remains open."
 
 [[item]]
 id = "AUTO-219-6"

From 1b561c02ca00cdd8785c608450fb40a254fa5d08 Mon Sep 17 00:00:00 2001
From: Fabio Lissi <fabio.lissi@gmail.com>
Date: Mon, 2 Nov 2026 17:37:51 -0600
Subject: [PATCH 076/109] Separate Batch conformance table from following notes

---
 docs/atn.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/atn.md b/docs/atn.md
index 26894a6dc7..b77799383b 100644
--- a/docs/atn.md
+++ b/docs/atn.md
@@ -574,6 +574,7 @@ Batch cancellation conformance (Photoshop 2026 observation above; PhotoCraft's p
 | Keep headless cancellation direct | `jobs.cancel` returns partial results without an interactive question | Implemented and tested, including a worker waiting for a desktop decision |
 | No progress bar | The desktop Batch preview is the visible feedback | Implemented, UI tested and visually checked |
 | Preserve error policy and log | Continue retains earlier errors and writes one final UTF-16 LE log | Implemented and tested with errors before and after Esc |
+
 - **Return value:** when any file failed, the Batch step itself reports "cancelled" (the dialog returns no
   descriptor); a script run with Stop For Errors reports success even though it stopped.
 

From 55a8d917de8ad8f247726a130384e3c032115b85 Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 00:50:41 +0100
Subject: [PATCH 077/109] Batch 13: #10755 and #10765 on top of batch 12

- Link Layers keeps main's measured toggle mapping (batch 12, #10628): played twice in the
  reference application it links, then unlinks. #10755's second, explicit `linked: true`
  entry for the same event was unreachable on import and contradicted that measurement, so
  it is dropped; Unlink stays explicit. Its tests now cover Unlink only, and `{}` exports.
- #10765: an ordinary Gradient Map now saves as `gradientMapEvent` (#10702 landed in batch 12).
- #10755: flattened pixels read with `Buffer::into_px()` since `Buffer` implements `Drop`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/atn_cmds/tests.rs         |  2 --
 .../engine/tests/it/atn_direct_adjustments.rs   |  2 +-
 crates/engine/tests/it/atn_newer_events.rs      | 17 ++++++++++-------
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/crates/engine/src/cmd/atn_cmds/tests.rs b/crates/engine/src/cmd/atn_cmds/tests.rs
index adfdc38c92..f468f72432 100644
--- a/crates/engine/src/cmd/atn_cmds/tests.rs
+++ b/crates/engine/src/cmd/atn_cmds/tests.rs
@@ -622,9 +622,7 @@ fn every_mapped_command_exports_and_imports_back() {
         ("filter.blur.shapeBlur", json!({"radius": 10})),
         ("layer.new.group", json!({"name": "G"})),
         ("layer.groupLayers", json!({})),
-        ("layer.linkLayers", json!({"linked": true})),
         ("layer.linkLayers", json!({"linked": false})),
-        ("layer.linkLayers", json!({"linked": true, "_atnNoTarget": true})),
         ("layer.linkLayers", json!({"linked": false, "_atnNoTarget": true})),
         ("layer.arrange.reverse", json!({})),
         ("layer.arrange.reverse", json!({"_atnNoTarget": true})),
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index dd26c6491a..955ea3f7a0 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -615,7 +615,7 @@ fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {
         vec![("image.adjustments.gradientMap".into(), json!({"stops":[[0,"#000000"],[1,"#ffffff"]]}))],
     );
     let (b, _) = atn_cmds::export("Ordinary", &[&action], &[], false).unwrap();
-    assert_eq!(atn::parse(&b).unwrap().actions[0].items[0].event, AtnEvent::Code(*b"GdMp"), "10702 owns the named-event repair");
+    assert_eq!(atn::parse(&b).unwrap().actions[0].items[0].event, AtnEvent::name("gradientMapEvent"), "an ordinary Gradient Map saves as the string event (#10702)");
 }
 
 /// Replacement preserves alpha and refuses locked or profile-incompatible surfaces before editing.
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index e864751340..77d22f8472 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -173,7 +173,8 @@ fn invalid_link_state_fails_without_editing() {
 
 #[test]
 fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
-    for (event, linked) in [("linkSelectedLayers", true), ("unlinkSelectedLayers", false)] {
+    // Link Layers keeps the measured toggle (main's Group F mapping); Unlink is explicit.
+    for (event, linked) in [("unlinkSelectedLayers", false)] {
         for initial in [vec![None, None, None, Some(93), Some(93)], vec![Some(77), Some(77), Some(77), Some(93), Some(93)]] {
             let descriptor = Descriptor::new("null").with("null", target());
             let mut s = fixture(&initial, &[0, 1]);
@@ -224,7 +225,8 @@ fn unsupported_link_descriptors_are_kept_and_ambiguous_exports_are_refused() {
             assert_eq!(parsed.actions[0].items[0].descriptor, Some(descriptor));
         }
     }
-    for params in [json!({}), json!({"linked": null}), json!({"linked": true, "layer": "Layer 0"}), json!({"linked": false, "layers": [1, 2]})] {
+    // `{}` is the measured Link Layers toggle and exports (main's Group F mapping).
+    for params in [json!({"linked": null}), json!({"linked": true, "layer": "Layer 0"}), json!({"linked": false, "layers": [1, 2]})] {
         let action = Action::new("A", vec![("layer.linkLayers".into(), params)]);
         assert!(atn_cmds::export("Links", &[&action], &[], false).is_err());
     }
@@ -284,7 +286,8 @@ fn target_events_keep_empty_and_explicit_target_descriptors_distinct() {
 
 #[test]
 fn bare_link_events_keep_their_operation_and_empty_keys() {
-    for (event, linked) in [("linkSelectedLayers", true), ("unlinkSelectedLayers", false)] {
+    // Link Layers keeps the measured toggle (main's Group F mapping); Unlink is explicit.
+    for (event, linked) in [("unlinkSelectedLayers", false)] {
         let initial = if linked { None } else { Some(77) };
         let mut s = fixture(&[initial, initial], &[0, 1]);
         assert_eq!(load(&mut s, &file(event, Descriptor::new(event)))["unsupported"], json!([]));
@@ -792,7 +795,7 @@ fn smart_target_events_copy_unpack_embed_and_refresh_real_contents() {
             let path = dir.path().join("linked.png");
             let mut s = smart_target_scene(event, &original, &replacement, path.to_str().unwrap());
             let before = s.active().unwrap().doc.clone();
-            let pixels = photocraft_compose::flatten(&before).px;
+            let pixels = photocraft_compose::flatten(&before).into_px();
             let contents_id = active_smart(&s).contents_id;
             load_targeted(&mut s, event, id, explicit);
             play(&mut s);
@@ -813,7 +816,7 @@ fn rasterize_all_event_visits_nested_and_top_level_smart_layers() {
         let nested = doc.remove(first).unwrap();
         doc.layers.push(Layer::group("Nested", vec![nested]));
         let before = s.active().unwrap().doc.clone();
-        let pixels = photocraft_compose::flatten(&before).px;
+        let pixels = photocraft_compose::flatten(&before).into_px();
         load_targeted(&mut s, "rasterizeAll", "layer.rasterize.allLayers", explicit);
         play(&mut s);
         assert!(s.active().unwrap().doc.walk().iter().all(|(_, _, layer)| !matches!(layer.content, LayerContent::Smart(_))));
@@ -980,9 +983,9 @@ fn radius_only_shape_blur_roundtrips_and_changes_pixels_including_default() {
         assert_eq!(saved.descriptor, Some(canonical.clone()));
         assert_eq!(load(&mut s, &file("shapeBlur", canonical))["unsupported"], json!([]));
         let before = s.active().unwrap().doc.clone();
-        let pixels = photocraft_compose::flatten(&before).px;
+        let pixels = photocraft_compose::flatten(&before).into_px();
         play(&mut s);
-        let blurred = photocraft_compose::flatten(&s.active().unwrap().doc).px;
+        let blurred = photocraft_compose::flatten(&s.active().unwrap().doc).into_px();
         assert_ne!(blurred, pixels);
         let mut direct = impulse_fixture();
         direct.execute("filter.blur.shapeBlur", json!({"radius": radius.unwrap_or(10.0)})).unwrap();

From 072dfd372410368aaad996f7231d697005f54352 Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 00:51:18 +0100
Subject: [PATCH 078/109] Batch 13: rustfmt the resolved files

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/tests/it/atn_direct_adjustments.rs | 6 +++++-
 crates/ui-egui/src/panels/layer_filter_ui.rs     | 3 +--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 955ea3f7a0..26a6e7e6fa 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -615,7 +615,11 @@ fn legacy_rgb_replace_color_and_ordinary_gradient_exports_are_unchanged() {
         vec![("image.adjustments.gradientMap".into(), json!({"stops":[[0,"#000000"],[1,"#ffffff"]]}))],
     );
     let (b, _) = atn_cmds::export("Ordinary", &[&action], &[], false).unwrap();
-    assert_eq!(atn::parse(&b).unwrap().actions[0].items[0].event, AtnEvent::name("gradientMapEvent"), "an ordinary Gradient Map saves as the string event (#10702)");
+    assert_eq!(
+        atn::parse(&b).unwrap().actions[0].items[0].event,
+        AtnEvent::name("gradientMapEvent"),
+        "an ordinary Gradient Map saves as the string event (#10702)"
+    );
 }
 
 /// Replacement preserves alpha and refuses locked or profile-incompatible surfaces before editing.
diff --git a/crates/ui-egui/src/panels/layer_filter_ui.rs b/crates/ui-egui/src/panels/layer_filter_ui.rs
index f3e2244f2c..e7916010e8 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui.rs
@@ -164,8 +164,7 @@ pub fn patched(current: &UiState, v: &serde_json::Value) -> Result<Filter, Strin
     }
     let mut f = Filter::of(current);
     if let Some(by) = o.get("by") {
-        f.by = serde_json::from_value(by.clone())
-            .map_err(|_| "layerFilter.by must be kind, name, mode, color, smartObject or artboard".to_string())?;
+        f.by = serde_json::from_value(by.clone()).map_err(|_| "layerFilter.by must be kind, name, mode, color, smartObject or artboard".to_string())?;
     }
     if let Some(kinds) = o.get("kinds") {
         let list = kinds.as_array().ok_or("layerFilter.kinds must be a list")?;

From 6a63960ec6eaef204be26f43f45c7d460595149d Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 01:04:44 +0100
Subject: [PATCH 079/109] Batch 13: settle the overlaps between the batched PRs

- Check Spelling: with #8726's measured form a `change` made in the dialog records no step
  (the reference application records one `spellCheck` step), so #4514's two tests that
  expected recorded `change` steps are removed; its portable recording stays for all else.
- Clippy `chunks_exact_to_as_chunks` in #10765's tests; a single-element loop in #10755's.
- docs/parity-checklist.md and docs/scorecard.md regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/type_spell_cmds.rs      | 33 -------------------
 .../engine/tests/it/atn_direct_adjustments.rs |  6 ++--
 crates/engine/tests/it/atn_newer_events.rs    |  6 ++--
 3 files changed, 7 insertions(+), 38 deletions(-)

diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index 016626e9ba..3aea104795 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -327,39 +327,6 @@ mod tests {
         text(&s.active().unwrap().doc, LayerId(id)).unwrap().to_string()
     }
 
-    #[test]
-    fn a_recorded_spelling_change_replays_on_a_named_nonactive_layer() {
-        let (mut s, id) = session("Teh");
-        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
-        s.execute("layer.new.layer", json!({"name": "Top"})).unwrap();
-        let replay = s.active().unwrap().doc.as_ref().clone();
-        s.execute("actions.record", json!({"name": "Fix spelling"})).unwrap();
-        s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
-        s.execute("actions.stop", json!({})).unwrap();
-        let steps = s.execute("actions.get", json!({"action": "Fix spelling"})).unwrap()["steps"].clone();
-        assert_eq!(steps[0][1]["layer"], name);
-        s.add_document(replay, None);
-        let played = s.execute("actions.play", json!({"action": "Fix spelling"})).unwrap();
-        assert!(played.get("failed").is_none(), "{played}");
-        assert_eq!(text_of(&s, id), "The");
-    }
-
-    #[test]
-    fn a_recorded_spelling_change_keeps_the_active_source_layer() {
-        let (mut s, id) = session("Teh");
-        let name = s.active().unwrap().doc.layer(LayerId(id)).unwrap().name.clone();
-        let replay = s.active().unwrap().doc.as_ref().clone();
-        s.execute("actions.record", json!({"name": "Fix active spelling"})).unwrap();
-        s.execute("edit.checkSpelling", json!({"action": "change", "layer": id, "start": 0, "end": 3, "word": "Teh", "replace": "The"})).unwrap();
-        s.execute("actions.stop", json!({})).unwrap();
-        let steps = s.execute("actions.get", json!({"action": "Fix active spelling"})).unwrap()["steps"].clone();
-        assert_eq!(steps[0][1]["layer"], name, "the change must retain its source layer");
-        s.add_document(replay, None);
-        let played = s.execute("actions.play", json!({"action": "Fix active spelling"})).unwrap();
-        assert!(played.get("failed").is_none(), "{played}");
-        assert_eq!(text_of(&s, id), "The");
-    }
-
     #[test]
     fn missing_named_spelling_layer_is_an_error_for_list_and_change_all() {
         let (mut s, _) = session("Teh");
diff --git a/crates/engine/tests/it/atn_direct_adjustments.rs b/crates/engine/tests/it/atn_direct_adjustments.rs
index 26a6e7e6fa..8f59433b9e 100644
--- a/crates/engine/tests/it/atn_direct_adjustments.rs
+++ b/crates/engine/tests/it/atn_direct_adjustments.rs
@@ -460,7 +460,7 @@ fn lab_replace_crosses_tile_edges_without_changing_unselected_native_pixels() {
             let original = raw(&s);
             s.execute("image.adjustments.replaceColor", json!({"labMinimum":[49,0,0],"labMaximum":[51,0,0],"fuzziness":0,"lightness":100})).unwrap();
             let after = raw(&s);
-            for (i, (pixel, original)) in after.chunks_exact(4).zip(original.chunks_exact(4)).enumerate() {
+            for (i, (pixel, original)) in after.as_chunks::<4>().0.iter().zip(original.as_chunks::<4>().0).enumerate() {
                 let inside = window.contains((i % width) as i32, (i / width) as i32);
                 let changed = selected == "none" || (selected == "window") == inside;
                 if changed {
@@ -629,7 +629,7 @@ fn lab_replace_preserves_alpha_and_rejects_locked_or_mismatched_surfaces() {
     let mut s = fixture("rgb", 32);
     let before = raw(&s);
     s.execute("image.adjustments.replaceColor", p.clone()).unwrap();
-    for (a, b) in raw(&s).chunks_exact(4).zip(before.chunks_exact(4)) {
+    for (a, b) in raw(&s).as_chunks::<4>().0.iter().zip(before.as_chunks::<4>().0) {
         assert_eq!(a[3], b[3]);
     }
     assert!(s.undo());
@@ -669,7 +669,7 @@ fn lab_replace_fractional_selection_preserves_f32_alpha_bits() {
         s.execute("image.adjustments.replaceColor", json!({"labMinimum":[0,-128,-128],"labMaximum":[100,127,127],"lightness":100})).unwrap();
         let after = raw(&s);
         assert_ne!(&after[8..11], &original[8..11]);
-        for (after, before) in after.chunks_exact(4).zip(original.chunks_exact(4)) {
+        for (after, before) in after.as_chunks::<4>().0.iter().zip(original.as_chunks::<4>().0) {
             assert_eq!(after[3].to_bits(), before[3].to_bits(), "coverage {coverage}");
         }
         assert!(s.undo());
diff --git a/crates/engine/tests/it/atn_newer_events.rs b/crates/engine/tests/it/atn_newer_events.rs
index 77d22f8472..acecf5ec7e 100644
--- a/crates/engine/tests/it/atn_newer_events.rs
+++ b/crates/engine/tests/it/atn_newer_events.rs
@@ -174,7 +174,8 @@ fn invalid_link_state_fails_without_editing() {
 #[test]
 fn atn_link_events_keep_descriptors_and_replay_the_requested_operation() {
     // Link Layers keeps the measured toggle (main's Group F mapping); Unlink is explicit.
-    for (event, linked) in [("unlinkSelectedLayers", false)] {
+    {
+        let (event, linked) = ("unlinkSelectedLayers", false);
         for initial in [vec![None, None, None, Some(93), Some(93)], vec![Some(77), Some(77), Some(77), Some(93), Some(93)]] {
             let descriptor = Descriptor::new("null").with("null", target());
             let mut s = fixture(&initial, &[0, 1]);
@@ -287,7 +288,8 @@ fn target_events_keep_empty_and_explicit_target_descriptors_distinct() {
 #[test]
 fn bare_link_events_keep_their_operation_and_empty_keys() {
     // Link Layers keeps the measured toggle (main's Group F mapping); Unlink is explicit.
-    for (event, linked) in [("unlinkSelectedLayers", false)] {
+    {
+        let (event, linked) = ("unlinkSelectedLayers", false);
         let initial = if linked { None } else { Some(77) };
         let mut s = fixture(&[initial, initial], &[0, 1]);
         assert_eq!(load(&mut s, &file(event, Descriptor::new(event)))["unsupported"], json!([]));

From 6c0f4d50b557342ace9974bae5286712b9177dd4 Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Tue, 3 Nov 2026 02:06:27 +0100
Subject: [PATCH 080/109] Crop: snap a Shift-corner drag where its handle is;
 test turned frames, Auto Center, presets

Snapping found the crop handle with the larger-extent rule, so during a
Shift corner drag it looked for guides next to a handle that wasn't
there: a guide 5.6 px from the handle on the diagonal didn't catch it,
and one 8.4 px away snapped the frame to the old rule's size.

The resize, Auto Center Preview and handle snapping now all read the
pointer through crop_ui::resize_point.

New tests: a turned frame in both modes, an exact size with Auto Center
Preview, a ratio preset keeping today's rule, and snapping to a guide.
Each fails when the piece it covers is reverted.
---
 crates/ui-egui/src/canvas/snap_ui.rs         |  11 +-
 crates/ui-egui/src/tools/crop_ui.rs          |  30 ++--
 crates/ui-egui/tests/it/crop_shift_corner.rs | 138 +++++++++++++++----
 3 files changed, 135 insertions(+), 44 deletions(-)

diff --git a/crates/ui-egui/src/canvas/snap_ui.rs b/crates/ui-egui/src/canvas/snap_ui.rs
index 4e1537d41b..e7b4f3324e 100644
--- a/crates/ui-egui/src/canvas/snap_ui.rs
+++ b/crates/ui-egui/src/canvas/snap_ui.rs
@@ -381,10 +381,13 @@ fn crop_handle(app: &PhotocraftApp, p: [f64; 2], mods: egui::Modifiers, targets:
     let deg = crate::crop_ui::angle(app);
     let ratio = crate::crop_ui::resize_ratio(app, rect, mods);
     let q = view.map_or(p, |view| crate::crop_mode::to_press(app, Some(view), p));
-    // The frame for the pointer at `q`, as `crop_ui` resizes it.
-    let frame_at = |q: [f64; 2]| match view {
-        Some(_) => crate::crop_mode::resized_frame(crate::crop_mode::LiveResize { rect, deg, hx, hy, start, q, ratio, alt: mods.alt }).map(|(f, _)| f),
-        None => Some(crate::crop_ui::resized_turned(rect, deg, hx, hy, [q[0] - start[0], q[1] - start[1]], ratio, mods.alt)),
+    // The frame for the pointer at `q`, as `crop_ui` resizes it (a ⇧ corner along its diagonal).
+    let frame_at = |q: [f64; 2]| {
+        let q = crate::crop_ui::resize_point(app, rect, hx, hy, start, q, mods);
+        match view {
+            Some(_) => crate::crop_mode::resized_frame(crate::crop_mode::LiveResize { rect, deg, hx, hy, start, q, ratio, alt: mods.alt }).map(|(f, _)| f),
+            None => Some(crate::crop_ui::resized_turned(rect, deg, hx, hy, [q[0] - start[0], q[1] - start[1]], ratio, mods.alt)),
+        }
     };
     let frame = frame_at(q)?;
     let at = |r: [f64; 4]| {
diff --git a/crates/ui-egui/src/tools/crop_ui.rs b/crates/ui-egui/src/tools/crop_ui.rs
index a1588ea7e6..003debc441 100644
--- a/crates/ui-egui/src/tools/crop_ui.rs
+++ b/crates/ui-egui/src/tools/crop_ui.rs
@@ -215,10 +215,17 @@ fn along_diagonal(r: [f64; 4], deg: f64, hx: i8, hy: i8, d: [f64; 2]) -> [f64; 2
     if vv > 0.0 && t.is_finite() { [t * v[0], t * v[1]] } else { d }
 }
 
-/// ⇧ on a corner with no ratio preset and no ⌥: the corner follows the frame's diagonal
-/// ([`along_diagonal`]). A preset, ⌥ ⇧ and the edge handles keep the larger-extent rule.
-fn follows_diagonal(app: &PhotocraftApp, hx: i8, hy: i8, mods: Modifiers) -> bool {
-    mods.shift && !mods.alt && hx != 0 && hy != 0 && preset_ratio(app).is_none()
+/// The pointer at `q` of a resize drag on handle (`hx`, `hy`) of frame `rect`, pressed at
+/// `start`, as the resize reads it. ⇧ on a corner with no ratio preset and no ⌥ follows the
+/// frame's diagonal ([`along_diagonal`]); a preset, ⌥ ⇧ and the edge handles keep the
+/// larger-extent rule, and the point is unchanged. The resize, Auto Center Preview and handle
+/// snapping all read the pointer through this, so the handle snaps where it is drawn.
+pub(crate) fn resize_point(app: &PhotocraftApp, rect: [f64; 4], hx: i8, hy: i8, start: [f64; 2], q: [f64; 2], mods: Modifiers) -> [f64; 2] {
+    if !(mods.shift && !mods.alt && hx != 0 && hy != 0 && preset_ratio(app).is_none()) {
+        return q;
+    }
+    let d = along_diagonal(rect, angle(app), hx, hy, [q[0] - start[0], q[1] - start[1]]);
+    [start[0] + d[0], start[1] + d[1]]
 }
 
 /// `[x0, y0, x1, y1]` with x0 ≤ x1, y0 ≤ y1.
@@ -952,13 +959,9 @@ fn follow_view_drag(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> bo
         }
         Some(CropDrag::Resize { hx, hy, start, rect, view: Some(view) }) => {
             // Auto Center Preview keeps the box centred while the handle follows the pointer.
-            let mut at = crate::crop_mode::to_press(app, Some(view), p);
+            let at = resize_point(app, rect, hx, hy, start, crate::crop_mode::to_press(app, Some(view), p), mods);
             let ratio = resize_ratio(app, rect, mods);
             let deg = angle(app);
-            if follows_diagonal(app, hx, hy, mods) {
-                let d = along_diagonal(rect, deg, hx, hy, [at[0] - start[0], at[1] - start[1]]);
-                at = [start[0] + d[0], start[1] + d[1]];
-            }
             crate::crop_mode::live_resize(app, crate::crop_mode::LiveResize { rect, deg, hx, hy, start, q: at, ratio, alt: mods.alt }, view);
         }
         _ => return false,
@@ -971,7 +974,10 @@ fn dragged_frame(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> Optio
     let ratio = preset_ratio(app);
     let space = app.crop.space;
     let deg = angle(app);
-    let diagonal = matches!(app.crop.drag, Some(CropDrag::Resize { hx, hy, .. }) if follows_diagonal(app, hx, hy, mods));
+    let resize_at = match app.crop.drag {
+        Some(CropDrag::Resize { hx, hy, start, rect, .. }) => resize_point(app, rect, hx, hy, start, p, mods),
+        _ => p,
+    };
     match app.crop.drag.as_mut()? {
         CropDrag::Draw { anchor, cur, last, .. } => {
             if space {
@@ -995,9 +1001,7 @@ fn dragged_frame(app: &mut PhotocraftApp, p: [f64; 2], mods: Modifiers) -> Optio
                 (w > 0.0 && h > 0.0).then(|| w / h)
             };
             let ratio = ratio.or_else(|| if mods.shift { keep() } else { None });
-            let d = [p[0] - start[0], p[1] - start[1]];
-            let d = if diagonal { along_diagonal(*rect, deg, *hx, *hy, d) } else { d };
-            Some(resized_turned(*rect, deg, *hx, *hy, d, ratio, mods.alt))
+            Some(resized_turned(*rect, deg, *hx, *hy, [resize_at[0] - start[0], resize_at[1] - start[1]], ratio, mods.alt))
         }
         CropDrag::Rotate { .. } | CropDrag::TurnImage { .. } | CropDrag::MoveImage { .. } => None,
     }
diff --git a/crates/ui-egui/tests/it/crop_shift_corner.rs b/crates/ui-egui/tests/it/crop_shift_corner.rs
index 6fba00ed02..e18e62bca8 100644
--- a/crates/ui-egui/tests/it/crop_shift_corner.rs
+++ b/crates/ui-egui/tests/it/crop_shift_corner.rs
@@ -6,30 +6,48 @@
 //! projected onto (800, 500) shortens the frame by 11.8 %). PhotoCraft let the larger relative
 //! extent win and committed 720 × 450.
 //!
-//! Driven through `ui.pointer`, as an agent or the canvas sends the drag; no GPU needed.
+//! Driven through `ui.pointer`, as an agent or the canvas sends the drag; no GPU needed. The Auto
+//! Center Preview test sends screen points through the view instead, as the mouse does, since the
+//! view pans with the frame during that drag.
 
 use photocraft_doc::{Color, ColorMode, Document, SampleType, Size};
 use photocraft_ui_egui::PhotocraftApp;
+use photocraft_ui_egui::canvas::{ToolEvent, ViewXform, tool_event};
 use photocraft_ui_egui::control::{ControlRequest, Outcome, handle};
+use photocraft_ui_egui::crop_ui;
 use serde_json::{Value, json};
 
-/// An 800 × 500 document at 100 % in a canvas it fits, the Crop tool's default frame up.
-fn crop_app(auto_center: bool) -> PhotocraftApp {
+/// The measured ⇧ drag.
+const DRAG: [f64; 2] = [-100.0, -50.0];
+
+#[derive(Default)]
+struct Setup {
+    auto_center: bool,
+    classic: bool,
+    /// Options-bar ratio preset, `""` for none.
+    ratio: &'static str,
+    snap: bool,
+}
+
+/// An 800 × 500 document at 100 % in a canvas it fits, the Crop tool's frame up.
+fn crop_app(s: Setup) -> PhotocraftApp {
     let doc = Document::with_background("crop", Size::new(800, 500), ColorMode::Rgb, SampleType::U8, Color::WHITE);
-    let mut s = photocraft_engine::Session::new();
-    s.add_document(doc, None);
-    let mut app = PhotocraftApp::new(s, Default::default());
+    let mut session = photocraft_engine::Session::new();
+    session.add_document(doc, None);
+    let mut app = PhotocraftApp::new(session, Default::default());
     app.sync_views();
-    app.ui.extras.snap = false;
+    app.ui.extras.snap = s.snap;
+    app.ui.extras.guides = true;
     app.ui.extras.rulers = false;
     app.ui.view.show.smart_guides = false;
     app.last_canvas_rect = egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(1600.0, 1000.0));
     let v = &mut app.ui.views[0];
     (v.zoom, v.center, v.fit_pending, v.rotation) = (1.0, [400.0, 250.0], false, 0.0);
-    app.ui.tool_options.crop_shield.auto_center_preview = auto_center;
+    app.ui.tool_options.crop_shield.auto_center_preview = s.auto_center;
+    app.ui.tool_options.crop_shield.classic_mode = s.classic;
+    app.ui.tool_options.crop_ratio = s.ratio.into();
     pointer(&mut app, json!({"tool": "Crop", "events": []}));
-    photocraft_ui_egui::crop_ui::ensure_frame(&mut app);
-    assert_eq!(app.ui.crop_rect, Some([0.0, 0.0, 800.0, 500.0]), "the default frame is the whole canvas");
+    crop_ui::ensure_frame(&mut app);
     app
 }
 
@@ -40,9 +58,22 @@ fn pointer(app: &mut PhotocraftApp, params: Value) {
     assert_eq!(v["ok"], true, "{v}");
 }
 
-/// Drags the bottom-right corner by `d` in steps, holding `mods`, and commits with ↵.
+/// The frame's (turned) bottom-right corner, where the drags start.
+fn corner(app: &PhotocraftApp) -> [f64; 2] {
+    crop_ui::corners(app.ui.crop_rect.expect("a frame"), crop_ui::angle(app))[2]
+}
+
+/// Commits with ↵ and returns the document size.
+fn commit(app: &mut PhotocraftApp) -> (u32, u32) {
+    photocraft_ui_egui::canvas::commit_crop(app);
+    let size = app.session.active().expect("a document").doc.size;
+    (size.width, size.height)
+}
+
+/// Drags the bottom-right corner by document vector `d` in steps through `ui.pointer`, holding
+/// `mods`, and commits.
 fn drag_corner_and_commit(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) -> (u32, u32) {
-    let (x, y) = (800.0, 500.0);
+    let [x, y] = corner(app);
     let mut events = vec![json!({"kind": "down", "x": x, "y": y})];
     events.extend((1..=4).map(|i| {
         let t = f64::from(i) / 4.0;
@@ -52,9 +83,7 @@ fn drag_corner_and_commit(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) ->
     let mut params = mods;
     params["events"] = Value::Array(events);
     pointer(app, params);
-    photocraft_ui_egui::canvas::commit_crop(app);
-    let size = app.session.active().expect("a document").doc.size;
-    (size.width, size.height)
+    commit(app)
 }
 
 fn assert_near(got: (u32, u32), want: (u32, u32), what: &str) {
@@ -64,33 +93,88 @@ fn assert_near(got: (u32, u32), want: (u32, u32), what: &str) {
 
 #[test]
 fn shift_corner_drag_follows_the_frames_diagonal() {
-    let mut app = crop_app(false);
-    let got = drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true}));
+    let mut app = crop_app(Setup::default());
+    assert_eq!(app.ui.crop_rect, Some([0.0, 0.0, 800.0, 500.0]), "the default frame is the whole canvas");
+    let got = drag_corner_and_commit(&mut app, DRAG, json!({"shift": true}));
     assert_near(got, (706, 441), "⇧ drag by (−100, −50)");
 }
 
 #[test]
 fn shift_corner_drag_outward_past_the_canvas_follows_the_diagonal() {
-    let mut app = crop_app(false);
+    let mut app = crop_app(Setup::default());
     // (100, 50) onto (800, 500) grows the frame by 11.8 %: 894.4 × 559.0, past the canvas.
     let got = drag_corner_and_commit(&mut app, [100.0, 50.0], json!({"shift": true}));
     assert_near(got, (894, 559), "⇧ drag by (100, 50)");
 }
 
+/// A turned frame: the diagonal turns with it, so the measured drag taken in the frame's own axes
+/// gives the measured size, in Classic Mode (the frame turns) and the default mode (the image
+/// turns). Projected onto the upright diagonal instead it gives about 714 × 446.
 #[test]
-fn shift_corner_drag_keeps_the_proportions_with_auto_center_preview() {
-    let mut app = crop_app(true);
-    let (w, h) = drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true}));
-    assert!(w < 800 && h < 500, "the frame shrank: {w} × {h}");
-    assert!((f64::from(w) / f64::from(h) - 1.6).abs() < 0.01, "8 : 5 kept: {w} × {h}");
+fn shift_corner_drag_on_a_turned_frame_follows_its_diagonal() {
+    for classic in [true, false] {
+        let mut app = crop_app(Setup { classic, ..Setup::default() });
+        app.ui.crop_angle = 30.0;
+        photocraft_ui_egui::crop_mode::sync_frame(&mut app);
+        let d = crop_ui::turn(DRAG, [0.0, 0.0], 30.0);
+        let got = drag_corner_and_commit(&mut app, d, json!({"shift": true}));
+        assert_near(got, (706, 441), &format!("⇧ drag on a frame turned 30°, Classic Mode {classic}"));
+    }
+}
+
+/// Auto Center Preview (the default): the box stays centred on screen and shrinks on both sides
+/// as the handle follows the pointer, so each extent changes by twice the projected drag:
+/// 800 − 2 × 94.4 = 611.2 and 500 − 2 × 59.0 = 382.0. With the larger relative extent winning it
+/// was 640 × 400.
+#[test]
+fn shift_corner_drag_follows_the_diagonal_with_auto_center_preview() {
+    let mut app = crop_app(Setup { auto_center: true, ..Setup::default() });
+    let shift = egui::Modifiers::SHIFT;
+    let [x, y] = corner(&app);
+    let from = ViewXform::active(&app).expect("a view").to_screen(x as f32, y as f32);
+    let to = from + egui::vec2(DRAG[0] as f32, DRAG[1] as f32);
+    // Each screen point is read through the view as it is then, as the canvas does every frame.
+    let at = |app: &PhotocraftApp, p: egui::Pos2| ViewXform::active(app).expect("a view").to_doc(p);
+    let [x, y] = at(&app, from);
+    tool_event(&mut app, ToolEvent::Down { x, y, pressure: 1.0 }, shift);
+    for i in 1..=4 {
+        let [x, y] = at(&app, from + (to - from) * (i as f32 / 4.0));
+        tool_event(&mut app, ToolEvent::Move { x, y, pressure: 1.0 }, shift);
+    }
+    let [x, y] = at(&app, to);
+    tool_event(&mut app, ToolEvent::Up { x, y }, shift);
+    assert_near(commit(&mut app), (611, 382), "⇧ drag with Auto Center Preview");
+}
+
+/// A ratio preset keeps today's rule (not measured): the larger relative extent wins. On the
+/// 500 × 500 frame 1 : 1 fits, (−100, −50) gives max(400, 450) = 450 square; along the diagonal
+/// it would be 425 square.
+#[test]
+fn shift_corner_drag_with_a_ratio_preset_is_unchanged() {
+    let mut app = crop_app(Setup { ratio: "1:1", ..Setup::default() });
+    assert_eq!(app.ui.crop_rect, Some([150.0, 0.0, 650.0, 500.0]), "the preset fits a 500 × 500 frame");
+    assert_near(drag_corner_and_commit(&mut app, DRAG, json!({"shift": true})), (450, 450), "⇧ with 1 : 1");
 }
 
 #[test]
 fn the_same_drag_without_shift_or_with_alt_is_unchanged() {
     // No ⇧: the corner follows the pointer freely, 700 × 450 as in Photoshop.
-    let mut app = crop_app(false);
-    assert_near(drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({})), (700, 450), "no ⇧");
+    let mut app = crop_app(Setup::default());
+    assert_near(drag_corner_and_commit(&mut app, DRAG, json!({})), (700, 450), "no ⇧");
     // ⌥ ⇧ (not measured, today's rule): about the centre, 600 × 400 grows to 8 : 5 as 640 × 400.
-    let mut app = crop_app(false);
-    assert_near(drag_corner_and_commit(&mut app, [-100.0, -50.0], json!({"shift": true, "alt": true})), (640, 400), "⌥ ⇧");
+    let mut app = crop_app(Setup::default());
+    assert_near(drag_corner_and_commit(&mut app, DRAG, json!({"shift": true, "alt": true})), (640, 400), "⌥ ⇧");
+}
+
+/// Snapping reads the handle where the ⇧ drag puts it, on the diagonal (x ≈ 705.6 for the
+/// measured drag), not where the larger-extent rule would (x = 720). The tolerance is 8 px at
+/// 100 %: a guide 5.6 px away catches the handle, one 8.4 px away doesn't.
+#[test]
+fn a_shift_corner_drag_snaps_where_its_handle_is() {
+    for (guide, want) in [(700.0, (700, 438)), (714.0, (706, 441))] {
+        let mut app = crop_app(Setup { snap: true, ..Setup::default() });
+        app.run("view.newGuide", json!({"orientation": "vertical", "position": guide})).expect("guide");
+        let got = drag_corner_and_commit(&mut app, DRAG, json!({"shift": true}));
+        assert_near(got, want, &format!("⇧ drag with a guide at x = {guide}"));
+    }
 }

From 3ce04b52f4cced665eb0cc80013bf5a55a06ba40 Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 03:02:19 +0100
Subject: [PATCH 081/109] Address CodeRabbit review: Batch writes, recording
 and dialog edge cases

- CLI batch: recursive inputs keep the engine's tree order for {serial};
  --format picks the encoder whatever extension --naming writes; the
  summary prints before --error-log is written.
- Batch: a jobs.cancel during a write keeps that file in `files`;
  Opened Files refuses a default-named result that replaces another open
  document's file; a recorded Save leaves a document changed when Batch
  writes nothing for it.
- Recording: folded Move-tool nudges add whole-pixel steps; a null
  Check Spelling `action` is recorded as Check Spelling.
- Linked files: a document without links lists none missing; a look
  whose links changed while it ran is dropped.
- Save for Web: a null or empty destination opens the picker; a rename
  while the picker is open writes the picked file.
- Actions: a Check Spelling step fails instead of replacing a dialog
  opened by hand.
- Docs: desktop Batch cancel flow, Check Spelling step shape, filter row
  history count.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/photocraft-cli/src/batch.rs             | 18 +++++---
 apps/photocraft-cli/tests/it/cli.rs          | 43 ++++++++++++++++++
 crates/engine/src/cmd/actions_cmds.rs        |  5 ++-
 crates/engine/src/cmd/actions_cmds/tests.rs  | 14 ++++++
 crates/engine/src/cmd/file_cmds/batch_run.rs | 32 ++++++++++++-
 crates/engine/src/cmd/file_cmds/tests.rs     | 35 +++++++++++++++
 crates/engine/src/cmd/type_spell_cmds.rs     | 12 ++++-
 crates/engine/src/link_watch.rs              | 47 +++++++++++++++++++-
 crates/ui-egui/src/dialogs/file_ui/tests.rs  | 27 +++++++++++
 crates/ui-egui/src/dialogs/file_ui/web.rs    | 10 ++++-
 crates/ui-egui/src/panels/actions.rs         |  8 ++--
 crates/ui-egui/src/panels/actions/tests.rs   | 18 ++++++++
 docs/batch-naming.md                         |  7 +--
 docs/control-protocol.md                     |  2 +-
 docs/ui-parity.md                            |  2 +-
 15 files changed, 258 insertions(+), 22 deletions(-)

diff --git a/apps/photocraft-cli/src/batch.rs b/apps/photocraft-cli/src/batch.rs
index 5becc70c31..e02be9f772 100644
--- a/apps/photocraft-cli/src/batch.rs
+++ b/apps/photocraft-cli/src/batch.rs
@@ -58,7 +58,7 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     if !a.in_place && same_dir(in_dir, out_dir) {
         return Err(CliError::OutIsIn(out_dir.to_path_buf()));
     }
-    let mut inputs: Vec<photocraft_engine::file_cmds::BatchInput> = if a.recursive {
+    let inputs: Vec<photocraft_engine::file_cmds::BatchInput> = if a.recursive {
         photocraft_engine::file_cmds::list_images_tree(&in_dir.to_string_lossy(), &out_dir.to_string_lossy(), "photocraft-cli batch")?
             .into_iter()
             .filter(|input| is_input(Path::new(&input.path)))
@@ -72,9 +72,11 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
                 images.push(photocraft_engine::file_cmds::BatchInput { path: path.to_string_lossy().into_owned(), rel_dir: String::new() });
             }
         }
+        // The tree listing already holds the engine's order (each folder's files, then its
+        // subfolders), which `{serial}` numbers; only the flat listing needs sorting.
+        images.sort_by(|a, b| a.path.cmp(&b.path));
         images
     };
-    inputs.sort_by(|a, b| a.path.cmp(&b.path));
     let (mut ok, mut failed) = (0, 0);
     // `--format .jpg` names outputs `<stem>.jpg`, as `--format jpg` does (#490).
     let format = a.export.format.as_deref().map(|f| f.strip_prefix('.').unwrap_or(f));
@@ -109,7 +111,8 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     let mut failures = Vec::new();
     for (input, target) in inputs.iter().zip(targets) {
         let input = Path::new(&input.path);
-        let ext = target.extension().map(|ext| ext.to_string_lossy().into_owned()).unwrap_or_else(|| "png".into());
+        // The selected format encodes the bytes, whatever extension `--naming` gives the file.
+        let ext = format.map(str::to_owned).or_else(|| input.extension().map(|e| e.to_string_lossy().into_owned())).unwrap_or_else(|| "png".into());
         let r = (|| -> Result<Vec<String>> {
             if let Some(parent) = target.parent() {
                 std::fs::create_dir_all(parent)?;
@@ -151,10 +154,6 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
             }
         }
     }
-    if let Some(path) = &a.error_log {
-        let bytes = photocraft_engine::file_cmds::encode_batch_error_log(failures.iter().map(|(file, error)| (file.as_str(), error.as_str())));
-        photocraft_format::atomic_write(path, &bytes)?;
-    }
     let skipped = inputs.len().saturating_sub(ok + failed);
     if skipped > 0 {
         let _ = writeln!(err, "--stop-on-error: {skipped} remaining input(s) skipped");
@@ -162,6 +161,11 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     } else {
         let _ = writeln!(out, "{ok} succeeded, {failed} failed");
     }
+    // After the summary, so a log that can't be written doesn't hide the counts.
+    if let Some(path) = &a.error_log {
+        let bytes = photocraft_engine::file_cmds::encode_batch_error_log(failures.iter().map(|(file, error)| (file.as_str(), error.as_str())));
+        photocraft_format::atomic_write(path, &bytes)?;
+    }
     if failed > 0 { Err(CliError::FilesFailed(failed)) } else { Ok(()) }
 }
 
diff --git a/apps/photocraft-cli/tests/it/cli.rs b/apps/photocraft-cli/tests/it/cli.rs
index fd1e66950b..500bf08252 100644
--- a/apps/photocraft-cli/tests/it/cli.rs
+++ b/apps/photocraft-cli/tests/it/cli.rs
@@ -513,6 +513,49 @@ fn batch_recursive_naming_stop_and_error_log() {
     assert!(!collision.join("a.png").exists());
 }
 
+/// `{serial}` numbers a recursive batch in the engine's order (a folder's files before its
+/// subfolders), `--format` encodes the bytes whatever extension `--naming` writes, and an
+/// `--error-log` that can't be written still leaves the summary printed.
+#[test]
+fn batch_naming_keeps_the_tree_order_and_the_selected_encoder() {
+    let root = tmp("batch-naming-order");
+    let input = root.join("in");
+    std::fs::create_dir_all(input.join("sub")).unwrap();
+    write_png(&input.join("z.png"), 8, 6, 3);
+    write_png(&input.join("sub/a.png"), 5, 4, 3);
+    let actions = root.join("actions.json");
+    std::fs::write(&actions, "[]").unwrap();
+    let run = |out: &Path, extra: &[&str]| {
+        bin().args(["batch", "--actions"]).arg(&actions).arg("--in").arg(&input).arg("--out").arg(out).args(extra).output().unwrap()
+    };
+    let png_width = |path: &Path| {
+        let bytes = std::fs::read(path).unwrap();
+        u32::from_be_bytes(bytes[16..20].try_into().unwrap())
+    };
+    let ordered = root.join("ordered");
+    let result = run(&ordered, &["--recursive", "--naming", "{serial:2}.{ext}"]);
+    assert!(result.status.success(), "{}", String::from_utf8_lossy(&result.stderr));
+    assert_eq!(png_width(&ordered.join("01.png")), 8, "the root file comes first");
+    assert_eq!(png_width(&ordered.join("02.png")), 5);
+
+    let jpeg = root.join("jpeg");
+    let result = run(&jpeg, &["--format", "jpg", "--naming", "{name}_{serial}"]);
+    assert!(result.status.success(), "{}", String::from_utf8_lossy(&result.stderr));
+    assert!(std::fs::read(jpeg.join("z_001")).unwrap().starts_with(&[0xff, 0xd8]), "JPEG bytes without an extension");
+    let png = root.join("png");
+    let result = run(&png, &["--format", "png", "--naming", "{name}.jpg"]);
+    assert!(result.status.success(), "{}", String::from_utf8_lossy(&result.stderr));
+    assert!(std::fs::read(png.join("z.jpg")).unwrap().starts_with(b"\x89PNG"), "PNG bytes under a .jpg name");
+
+    let log = root.join("log-is-a-folder");
+    std::fs::create_dir_all(&log).unwrap();
+    let result = run(&root.join("logged"), &["--error-log", &log.to_string_lossy()]);
+    let stdout = String::from_utf8_lossy(&result.stdout);
+    assert!(!result.status.success(), "{stdout}");
+    assert!(stdout.contains("1 succeeded, 0 failed"), "{stdout}");
+    std::fs::remove_dir_all(root).unwrap();
+}
+
 #[test]
 fn batch_skips_recorded_view_and_save_steps() {
     let d = tmp("batch-shell-steps");
diff --git a/crates/engine/src/cmd/actions_cmds.rs b/crates/engine/src/cmd/actions_cmds.rs
index 3d9e0d82ef..ddeeb8c13f 100644
--- a/crates/engine/src/cmd/actions_cmds.rs
+++ b/crates/engine/src/cmd/actions_cmds.rs
@@ -459,8 +459,9 @@ fn fold_recorded_nudges(steps: impl IntoIterator<Item = (String, Value)>) -> Vec
             .and_then(|p| p.get("coalesce").and_then(Value::as_str).filter(|run| run.starts_with("nudge:")))
             .map(str::to_string);
         if let Some(run) = &run {
-            let dx = params.get("dx").and_then(Value::as_f64);
-            let dy = params.get("dy").and_then(Value::as_f64);
+            // `layer.translate` moves each step by whole pixels, so the fold adds rounded steps.
+            let dx = params.get("dx").and_then(Value::as_f64).map(f64::round);
+            let dy = params.get("dy").and_then(Value::as_f64).map(f64::round);
             if let (Some(dx), Some(dy)) = (dx, dy)
                 && dx.is_finite()
                 && dy.is_finite()
diff --git a/crates/engine/src/cmd/actions_cmds/tests.rs b/crates/engine/src/cmd/actions_cmds/tests.rs
index b0bbc2810c..8f38b142d5 100644
--- a/crates/engine/src/cmd/actions_cmds/tests.rs
+++ b/crates/engine/src/cmd/actions_cmds/tests.rs
@@ -395,6 +395,20 @@ fn recording_folds_one_run_of_move_tool_nudges() {
     assert_eq!(steps, &[("layer.translate".into(), json!({"dx": 3.0, "dy": 10.0})), ("layer.translate".into(), json!({"dx": 0.0, "dy": 1.0}))]);
 }
 
+/// Each nudge moves by whole pixels, so two 0.6 px steps fold into the 2 px they moved, not 1.2.
+#[test]
+fn folded_nudges_add_whole_pixel_steps() {
+    let mut s = Session::new();
+    s.execute("file.new", json!({"width": 24, "height": 24, "background": "transparent"})).unwrap();
+    s.execute("layer.new.layer", json!({"name": "Target"})).unwrap();
+    s.execute("actions.record", json!({"name": "Nudge"})).unwrap();
+    for _ in 0..2 {
+        s.execute("layer.translate", json!({"dx": 0.6, "dy": 0.0, "coalesce": "nudge:1"})).unwrap();
+    }
+    s.execute("actions.stop", json!({})).unwrap();
+    assert_eq!(s.actions.list[0].steps, [("layer.translate".into(), json!({"dx": 2.0, "dy": 0.0}))]);
+}
+
 #[test]
 fn recording_document_activation_uses_opening_order_offset() {
     let mut s = Session::new();
diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index c7e393bd1b..7d62d16f45 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -366,7 +366,13 @@ pub(super) fn process_batch_outputs(
         let result = process_one(raw_ppi, path, out, save, ProcessOptions { format: Some(format), written: None, ctx: Some(ctx) }, f);
         if ctx.cancelled() {
             ctx.publish_batch_preview(path, None);
-            done = index;
+            // A cancel that lands while the result is written still leaves that file written.
+            if result.is_ok() {
+                files.push(out.clone());
+                done = index + 1;
+            } else {
+                done = index;
+            }
             break;
         }
         if ctx.batch_take_interrupt() {
@@ -642,12 +648,21 @@ fn batch_open_documents(
                 .collect(),
         })
     };
+    // As for a folder: no result may replace another open document's file.
+    #[cfg(not(target_arch = "wasm32"))]
+    if let Some(paths) = &planned {
+        let plan: Vec<(String, String)> = originals.iter().map(|(_, _, path)| path.clone()).zip(paths.iter().cloned()).collect();
+        validate_flat_outputs(&plan)?;
+    }
     validate_error_log(policy, originals.iter().map(|(_, _, path)| path.clone()), planned.iter().flat_map(|paths| paths.iter().cloned()))?;
     let mut files = Vec::new();
     let mut errors = Vec::new();
     let mut stopped = None;
     let mut done = 0;
     for (index, (id, name, path)) in originals.iter().enumerate() {
+        // The document a recorded Save / Save As marked as saved, with its earlier saved
+        // revision: when Batch then writes nothing, it reads as changed again.
+        let mut marked: Option<(u64, u64)> = None;
         let result = (|| -> Result<()> {
             let position = s.documents().iter().position(|state| state.doc.id.0 == *id).ok_or(EngineError::NoDocument)?;
             s.set_active(position);
@@ -656,7 +671,11 @@ fn batch_open_documents(
                 if batch_save_point(command) {
                     let state = s.active_mut().ok_or(EngineError::NoDocument)?;
                     saved = Some(state.doc.clone());
-                    if command != "file.saveACopy" {
+                    // With no destination nothing is written, so the document stays changed.
+                    if command != "file.saveACopy" && planned.is_some() {
+                        if marked.is_none() {
+                            marked = Some((state.doc.id.0, state.saved_revision));
+                        }
                         state.saved_revision = state.revision;
                     }
                     continue;
@@ -679,6 +698,15 @@ fn batch_open_documents(
             Ok(())
         })();
         done = index + 1;
+        if result.is_err()
+            && let Some((doc, revision)) = marked
+            && let Some(position) = s.documents().iter().position(|state| state.doc.id.0 == doc)
+        {
+            s.set_active(position);
+            if let Some(state) = s.active_mut() {
+                state.saved_revision = revision;
+            }
+        }
         if let Err(error) = result {
             errors.push(json!({"document": name, "error": error.to_string()}));
             if policy.stop_on_error {
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 808150c152..c8dd6d060e 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -445,6 +445,41 @@ fn batch_open_source_save_as_then_close_ask_writes_the_result() {
     assert!(session.documents().is_empty());
 }
 
+#[test]
+fn batch_open_source_refuses_a_result_that_replaces_another_open_file() {
+    let dir = tmp("batch-open-replaces-input");
+    let mut session = Session::new();
+    // Saved as PNG under its default name, `a.jpg`'s result is the open `a.png`'s file.
+    for (name, format) in [("a.jpg", "jpg"), ("a.png", "png")] {
+        let path = png(&dir, name, 8, 6, "#ff0000");
+        session.execute("file.openAs", json!({"path": path, "as": format})).unwrap();
+    }
+    let before = std::fs::read(join(&dir, "a.png")).unwrap();
+    let error = session
+        .execute("file.automate.batch", json!({"source": "open", "steps": [["image.imageRotation.90cw", {}]], "output": dir, "format": "png"}))
+        .unwrap_err();
+    assert!(error.to_string().contains("replace another input"), "{error}");
+    assert_eq!(std::fs::read(join(&dir, "a.png")).unwrap(), before, "nothing is written before the refusal");
+}
+
+#[test]
+fn batch_open_source_save_step_leaves_an_unwritten_document_changed() {
+    let mut session = Session::new();
+    session.execute("file.new", json!({"name": "First", "width": 8, "height": 6})).unwrap();
+    let steps = json!([["image.adjustments.invert", {}], ["file.save", {}]]);
+    // No destination: nothing is written.
+    let result = session.execute("file.automate.batch", json!({"source": "open", "steps": steps})).unwrap();
+    assert_eq!(result["errors"], json!([]), "{result}");
+    assert!(session.documents()[0].is_dirty(), "a document Batch did not write stays changed");
+    // A destination that can't be written: the write fails.
+    let dir = tmp("batch-open-save-fails");
+    let blocker = join(&dir, "not-a-folder");
+    std::fs::write(&blocker, b"file").unwrap();
+    let result = session.execute("file.automate.batch", json!({"source": "open", "steps": steps, "output": blocker, "format": "png"})).unwrap();
+    assert_eq!(result["errors"].as_array().map(Vec::len), Some(1), "{result}");
+    assert!(session.documents()[0].is_dirty(), "a failed write leaves the document changed");
+}
+
 #[cfg(unix)]
 #[test]
 fn batch_error_log_rejects_a_dangling_link_to_a_planned_output() {
diff --git a/crates/engine/src/cmd/type_spell_cmds.rs b/crates/engine/src/cmd/type_spell_cmds.rs
index 3aea104795..46e007d290 100644
--- a/crates/engine/src/cmd/type_spell_cmds.rs
+++ b/crates/engine/src/cmd/type_spell_cmds.rs
@@ -207,7 +207,7 @@ fn remove_word(s: &mut Session, p: &Value) -> Result<Value> {
 /// Whether an action records this call: only Check Spelling itself (no `action`), which the
 /// dialog runs when it closes. Its corrections, dictionary edits and lookups are not recorded.
 pub(crate) fn records(p: &Value) -> bool {
-    p.get("action").is_none()
+    p.get("action").is_none_or(Value::is_null)
 }
 
 /// The step a recorded Check Spelling becomes: `{"allLayers"}`, `false` when it checked one layer.
@@ -442,6 +442,16 @@ mod tests {
         assert_eq!(s.actions.list[0].dialogs.len(), 2);
     }
 
+    /// `"action": null` runs Check Spelling itself, so it is recorded as one.
+    #[test]
+    fn a_null_action_is_recorded_as_check_spelling() {
+        let (mut s, _) = session("Teh end");
+        s.execute("actions.record", json!({"name": "Null"})).unwrap();
+        s.execute("edit.checkSpelling", json!({"action": null})).unwrap();
+        s.execute("actions.stop", json!({})).unwrap();
+        assert_eq!(s.actions.list[0].steps, [("edit.checkSpelling".to_string(), json!({"allLayers": true}))]);
+    }
+
     #[test]
     fn played_check_spelling_without_its_dialog_changes_nothing() {
         let (mut s, id) = session("Teh end");
diff --git a/crates/engine/src/link_watch.rs b/crates/engine/src/link_watch.rs
index 21f7007302..893933fd80 100644
--- a/crates/engine/src/link_watch.rs
+++ b/crates/engine/src/link_watch.rs
@@ -96,8 +96,10 @@ impl Session {
         }
         let Some(st) = self.active() else { return };
         let (doc, files) = (st.doc.id.0, resolved_files(st));
-        // Nothing to look at: no links, or none that is followed.
+        // Nothing to look at: no links, or none that is followed. None of them is listed as
+        // missing either, so a link added back isn't shown missing before its first look.
         if files.iter().all(|(_, file, _)| file.is_none()) {
+            self.link_missing.retain(|(d, _)| *d != doc);
             return;
         }
         let slot: LinkScan = Arc::default();
@@ -139,6 +141,13 @@ impl Session {
     pub fn poll_link_scan(&mut self) -> Option<Result<Value>> {
         let (doc, stamps) = self.link_scan.as_ref()?.lock().unwrap_or_else(PoisonError::into_inner).take()?;
         self.link_scan = None;
+        // A relink or embed while the look ran: it stamped files the document no longer links in
+        // that way, so drop it; the next look takes the current links.
+        if let Some(st) = self.active().filter(|st| st.doc.id.0 == doc)
+            && !linked_files(&st.doc).iter().map(|(p, ids)| (p, ids)).eq(stamps.iter().map(|(p, ids, _)| (p, ids)))
+        {
+            return Some(Ok(json!({"updated": []})));
+        }
         Some(self.apply_link_stamps(doc, stamps))
     }
 
@@ -392,6 +401,42 @@ mod tests {
         assert!(s.missing_links().is_empty());
     }
 
+    #[test]
+    fn a_document_without_links_lists_none_missing() {
+        let d = dir("unlinked");
+        let path = d.join("art.png");
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, id) = placed(&path);
+        std::fs::remove_file(&path).unwrap();
+        s.execute("layer.smartObjects.updateChanged", json!({})).unwrap();
+        assert_eq!(s.missing_links().len(), 1);
+        s.execute("layer.delete", json!({"layer": id})).unwrap();
+        s.start_link_scan();
+        assert!(s.missing_links().is_empty(), "the last linked layer is gone");
+    }
+
+    #[test]
+    fn a_look_at_links_that_changed_meanwhile_is_dropped() {
+        let d = dir("relinked");
+        let path = d.join("art.png");
+        std::fs::write(&path, png(10, 10, "#ff0000")).unwrap();
+        let (mut s, layer) = placed(&path);
+        let doc = s.active().unwrap().doc.id.0;
+        let stored = super::linked_files(&s.active().unwrap().doc)[0].0.clone();
+        let inject = |s: &mut Session, file: &str| {
+            let scan = std::sync::Arc::new(std::sync::Mutex::new(Some((doc, vec![(file.to_string(), vec![layer], None)]))));
+            s.link_scan = Some(scan);
+        };
+        // Taken before a relink: its file is no longer linked.
+        inject(&mut s, &d.join("before-relink.png").to_string_lossy());
+        assert_eq!(s.poll_link_scan().unwrap().unwrap(), json!({"updated": []}));
+        assert!(s.missing_links().is_empty(), "a file no longer linked is not listed");
+        // Taken of the current links: applied.
+        inject(&mut s, &stored);
+        s.poll_link_scan().unwrap().unwrap();
+        assert_eq!(s.missing_links(), [stored].into());
+    }
+
     #[test]
     fn a_background_look_updates_changed_files() {
         let d = dir("scan");
diff --git a/crates/ui-egui/src/dialogs/file_ui/tests.rs b/crates/ui-egui/src/dialogs/file_ui/tests.rs
index 3824530214..e3ab707248 100644
--- a/crates/ui-egui/src/dialogs/file_ui/tests.rs
+++ b/crates/ui-egui/src/dialogs/file_ui/tests.rs
@@ -314,6 +314,33 @@ fn save_for_web_with_the_suggested_name_records_only_the_folder() {
     let _ = std::fs::remove_dir_all(&dir);
 }
 
+/// A null `folder` is no destination: the picker asks. A document renamed while the picker is
+/// open writes the picked file, not one named after the new name.
+#[test]
+fn save_for_web_writes_the_picked_file_when_no_folder_is_given_or_the_name_changed() {
+    let dir = std::env::temp_dir().join(format!("pc-webui-renamed-{}", std::process::id()));
+    std::fs::create_dir_all(&dir).unwrap();
+    for rename in [false, true] {
+        let (mut app, ctx) = app();
+        let target = dir.join("web.png").to_string_lossy().into_owned();
+        let (dialog, _) = crate::file_dialog::fake(vec![Some(crate::file_dialog::FileDialogAnswer::SaveTo(target.clone()))]);
+        app.services.file_dialog = Some(dialog);
+        let id = open_web(&mut app);
+        let fields = &mut app.ui.dialog_mut(id).unwrap().fields;
+        fields.insert("format".into(), json!("png24"));
+        fields.insert("folder".into(), Value::Null);
+        crate::dialogs::confirm(&mut app, id).unwrap();
+        if rename {
+            std::sync::Arc::make_mut(&mut app.session.active_mut().unwrap().doc).name = "renamed".into();
+        }
+        app.poll_file_dialog(&ctx, None);
+        assert!(std::path::Path::new(&target).exists(), "rename {rename}: {target}");
+        assert!(!dir.join("renamed.png").exists(), "rename {rename}");
+        let _ = std::fs::remove_file(&target);
+    }
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
 #[test]
 fn save_for_web_starts_at_the_current_document_size() {
     let (mut app, _) = app();
diff --git a/crates/ui-egui/src/dialogs/file_ui/web.rs b/crates/ui-egui/src/dialogs/file_ui/web.rs
index 5a14f2a3e0..8e41fc2288 100644
--- a/crates/ui-egui/src/dialogs/file_ui/web.rs
+++ b/crates/ui-egui/src/dialogs/file_ui/web.rs
@@ -531,6 +531,10 @@ pub(super) fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Re
         authorize(&prepared)?;
         p = prepared;
     }
+    // A null or empty destination is none: the picker asks for one.
+    if let Some(fields) = p.as_object_mut() {
+        fields.retain(|key, value| !(matches!(key.as_str(), "path" | "dir" | "folder") && (value.is_null() || value.as_str() == Some(""))));
+    }
     if p.get("path").is_some() || p.get("dir").is_some() || p.get("folder").is_some() {
         return save_for_web(app, p);
     }
@@ -546,7 +550,11 @@ pub(super) fn web_confirm(app: &mut PhotocraftApp, f: &Map<String, Value>) -> Re
             let dir = path.rfind(['/', '\\']).map(|i| path[..i].to_string()).unwrap_or_else(|| ".".into());
             p["dir"] = json!(dir);
             p["html"] = json!(html);
-        } else if let Some(folder) = kept_name_folder(&path, &base, st.format.ext()) {
+        } else if let Some(folder) = kept_name_folder(&path, &base, st.format.ext())
+            // A save that renamed the document meanwhile: the engine would name the file after
+            // the new name, not the one picked.
+            && app.session.active().is_some_and(|state| photocraft_doc::slices::base_name(&state.doc) == base)
+        {
             // The suggested name kept: only the folder, so a recorded action saves each
             // document under its own name, as in Photoshop (#5305).
             p["folder"] = json!(folder);
diff --git a/crates/ui-egui/src/panels/actions.rs b/crates/ui-egui/src/panels/actions.rs
index 9bd77be93c..c627b52a2e 100644
--- a/crates/ui-egui/src/panels/actions.rs
+++ b/crates/ui-egui/src/panels/actions.rs
@@ -254,11 +254,13 @@ fn play_owned(app: &mut PhotocraftApp, params: &Value, suspended: Option<Value>)
             break;
         }
         // Check Spelling's dialog opens with Check All Layers as recorded; Done continues the action.
-        // While another action waits at the open dialog, this step fails and the waiting one keeps it.
+        // While the dialog is open (for another action or by hand), this step fails and the open
+        // one keeps its place and ignored words.
         // A correction (`action` set) opens no dialog and runs below.
         if action.dialogs.contains(&i) && !app.automation_input && id == "edit.checkSpelling" && p.get("action").is_none() {
-            if app.ui.type_panels.spell.as_ref().is_some_and(|d| d.resume.is_some()) {
-                failed = Some(json!({"step": i, "id": id, "error": "Check Spelling is already open for another action"}));
+            if let Some(open) = app.ui.type_panels.spell.as_ref() {
+                let error = if open.resume.is_some() { "Check Spelling is already open for another action" } else { "Check Spelling is already open" };
+                failed = Some(json!({"step": i, "id": id, "error": error}));
                 break;
             }
             if let Err(error) = crate::type_panels_ui::open_spelling(app, p.get("allLayers").and_then(Value::as_bool).unwrap_or(true)) {
diff --git a/crates/ui-egui/src/panels/actions/tests.rs b/crates/ui-egui/src/panels/actions/tests.rs
index 37f28a7380..cfe2214de2 100644
--- a/crates/ui-egui/src/panels/actions/tests.rs
+++ b/crates/ui-egui/src/panels/actions/tests.rs
@@ -1606,6 +1606,24 @@ fn a_check_spelling_step_with_its_dialog_opens_it_and_done_continues() {
     assert_eq!(texts, ["Teh cat"]);
 }
 
+/// Check Spelling opened by hand keeps its place: an action's Check Spelling step fails instead
+/// of replacing it.
+#[test]
+fn a_check_spelling_step_fails_while_the_dialog_is_open_by_hand() {
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), crate::Services::default());
+    app.run("file.new", json!({"width": 300, "height": 100})).unwrap();
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Teh cat"})).unwrap();
+    let mut a = Action::new("Spell", vec![("edit.checkSpelling".into(), json!({"allLayers": false})), ("layer.new.layer".into(), json!({"name": "after"}))]);
+    a.dialogs.insert(0);
+    app.session.actions.list.push(a);
+    crate::type_panels_ui::open_spelling(&mut app, true).unwrap();
+    let v = play(&mut app, &json!({"action": "Spell"})).unwrap();
+    assert_eq!(v["failed"]["error"], "Check Spelling is already open", "{v}");
+    let d = app.ui.type_panels.spell.as_ref().expect("the dialog stays open");
+    assert!(d.all_layers && d.resume.is_none(), "the hand-opened dialog is kept");
+    assert!(!layer_names(&app).contains(&"after".to_string()));
+}
+
 /// A correction step (`action` set) runs as it did before the dialog toggle applied to Check
 /// Spelling: its dialog switch opens nothing.
 #[test]
diff --git a/docs/batch-naming.md b/docs/batch-naming.md
index b0e1b4bd4b..02e4d10f04 100644
--- a/docs/batch-naming.md
+++ b/docs/batch-naming.md
@@ -66,6 +66,7 @@ dot only at the end. `batch_include_all_subfolders`,
 `batch_naming_later_result_replaces_the_earlier_one`, and
 `extension_component_only_adds_a_dot_at_the_end` check those cases. PhotoCraft deliberately
 rejects a plan that would replace another input file before it is read, to prevent data loss.
-It keeps a progress display and immediate cancellation in the UI so headless control clients can
-observe and stop a batch. The measured Photoshop dialog has no progress display and asks whether
-to continue or stop after Esc; those differences remain open under AUTO-219-5.
+The desktop Batch follows the measured flow: it shows no progress in the status bar, previews each
+input read-only on the canvas, and Esc asks whether to continue or stop. Headless control clients
+still read the job's progress and stop it with `jobs.cancel`. The inputs are not live tabs with
+Layers panel content, so AUTO-219-5 stays partial.
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 3696ac62e7..8cd2abd529 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -152,7 +152,7 @@ store expose and persist the same setting; scripts keep using canonical command
 | `actions.list` | `{}` → `{actions:[{name, steps}], recording}` (the name being recorded, or null) |
 | `actions.get` | `{"action": name or index}` → `{name, steps:[[id, params], …], disabled:[step, …]}`. `steps` is the shape `file.automate.batch` and droplets take; `disabled` lists the 0-based steps playback skips |
 | `actions.record` | `{"name":"Red"}` starts a new action (default name `Action N`). `{"action": name or index}` appends to one that exists |
-| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped only when it is the sole selected layer and does not supply source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`, `edit.checkSpelling`). Otherwise, including when several layers are selected, it is recorded by its unique name; `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
+| `actions.stop` | `{}` → `{action, steps}`. Copies replayable journal entries since `actions.record` (queries and action-editing commands omitted). For portable playback, an active `layer` id is dropped only when it is the sole selected layer and does not supply source content (`layer.new.frame`, `select.loadSelection`, `type.createSelection`, `edit.checkSpelling`; a Check Spelling step keeps only `allLayers`, as the reference application's step does). Otherwise, including when several layers are selected, it is recorded by its unique name; `layer.select` records `{"name":"Layer","occurrence":0}`. Type tool keystrokes on a new layer fold into its `type.create` step; edits on an existing text layer retain separate replacements so styled text between edited spans survives replay. For commands other than `layer.select`, ambiguous layer names keep the id and require a unique name for portable playback |
 | `actions.play` | `{"action": name or index, "from": step?}`. `from` and `failed.step` are 0-based. Returns `{action, ran, failed?:{step, id, error}}` and still returns ok when a step fails, so a partial run is reported. Leaves one history step per step that ran. Supports nested action calls up to 16 levels, rejecting cycles. While recording, playing another action appends one named `actions.play` step instead of its expanded commands. On an untrusted session each step is authorized the same way as a top-level command |
 | `actions.move` | `{"action": name or index, "step": index?, "to": index}` moves a step within its action, or moves the whole action when `step` is omitted. `to` is the final zero-based index. Pending steps can be reordered while recording; invalid moves leave the list unchanged. |
 | `actions.delete` | `{"action": name or index, "step": index?}`. With a zero-based `step`: `{action, deletedStep, steps}`, also allowed while recording. Without `step`: `{deleted}`, refused while recording |
diff --git a/docs/ui-parity.md b/docs/ui-parity.md
index 82090bfedb..3a02c67374 100644
--- a/docs/ui-parity.md
+++ b/docs/ui-parity.md
@@ -267,7 +267,7 @@ Paragraph; the rest open as in-app floating windows.
 | Date | Change | Summary |
 |---|---|---|
 | 2026-11-01 | minor | Every preference takes effect: 11 of 183 do nothing (was 12); Graphics Adapter always worked, but startup read it by raw JSON key, which the scorecard audit can't see |
-| 2026-10-31 | minor | Layers panel filter-type dropdown: Color filters by the layers' label colour (#5898); Kind, Name, Mode and Color, the other five missing; no percentage changed |
+| 2026-10-31 | minor | Layers panel filter-type dropdown: Color filters by the layers' label colour (#5898); Kind, Name, Mode, Color, Smart Object and Artboard, the other three missing; no percentage changed |
 | 2026-10-29 | minor | Paragraph box overflow: text a box can't hold enlarges the box's lower-right handle and shows a black + in it, as the reference application does (#8311); agents read `typeBoxOverflow` in `ui.inspect`. Not a new command, so no percentage changed |
 | 2026-10-28 | minor | The text and gradient stop Color Pickers preview the picked colour on the canvas before OK, as Photoshop's do (#5530); no percentage changed |
 | 2026-10-27 | minor | Shape Fill/Stroke popover as Photoshop's (paint types, Color Picker button, Recently Used Colors, swatch folders, with the Gradient tab) and every colour swatch opens the full Color Picker; rows added (partial, done); Recently Used Colors is a new preference, so 12 of 183 do nothing; no percentage changed; 2026-10-30: the swatches preview live while their Color Picker is open |

From e2252cf3bbe4af99f93072cd6e34d3565aa10e48 Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Tue, 3 Nov 2026 04:14:20 +0100
Subject: [PATCH 082/109] Crop: a turned Shift-corner drag snaps by sliding
 along its diagonal

On a turned frame a corner with a ratio (a Shift corner's diagonal or an
options-bar preset) can only slide along its turned diagonal. Handle
snapping moved the handle sideways onto the guide in canvas axes, and the
ratio then put it back off the line: a Shift corner stopped short of the
guide and lost its snap line, and a preset corner grew away from it.
crop_handle now slides the corner along the diagonal onto the nearest line
it reached. Upright frames keep the existing ratio solve.

Tests: a turned frame snapping to a guide with Shift and with an 8:5
preset, in Classic Mode and the default mode; Shift on the top-right and
bottom-left corners, which use the other diagonal.
---
 crates/ui-egui/src/canvas/snap_ui.rs         | 30 ++++++++++++----
 crates/ui-egui/src/tools/crop_ui/tests.rs    | 20 +++++++++++
 crates/ui-egui/tests/it/crop_shift_corner.rs | 36 +++++++++++++++++++-
 3 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/crates/ui-egui/src/canvas/snap_ui.rs b/crates/ui-egui/src/canvas/snap_ui.rs
index e7b4f3324e..e360202fb1 100644
--- a/crates/ui-egui/src/canvas/snap_ui.rs
+++ b/crates/ui-egui/src/canvas/snap_ui.rs
@@ -420,17 +420,33 @@ fn crop_handle(app: &PhotocraftApp, p: [f64; 2], mods: egui::Modifiers, targets:
     let original = at(rect);
     let travel = crate::crop_ui::turn([handle[0] - original[0], handle[1] - original[1]], [0.0, 0.0], -deg);
     let mut local = [(travel[0] + d[0]) / scale, (travel[1] + d[1]) / scale];
-    if deg == 0.0
-        && hx != 0
+    if hx != 0
         && hy != 0
         && let Some(k) = ratio
     {
-        // A corner with a ratio has one degree of freedom. Put the other axis on the same
-        // ratio, rather than letting the raw pointer's unused axis override the snapped edge.
-        if lines.iter().any(|line| line.vertical) {
-            local[1] = f64::from(hy) * ((rect[2] - rect[0] + grow * f64::from(hx) * local[0]) / k - (rect[3] - rect[1])) / grow;
+        if deg == 0.0 {
+            // A corner with a ratio has one degree of freedom. Put the other axis on the same
+            // ratio, rather than letting the raw pointer's unused axis override the snapped edge.
+            if lines.iter().any(|line| line.vertical) {
+                local[1] = f64::from(hy) * ((rect[2] - rect[0] + grow * f64::from(hx) * local[0]) / k - (rect[3] - rect[1])) / grow;
+            } else {
+                local[0] = f64::from(hx) * ((rect[3] - rect[1] + grow * f64::from(hy) * local[1]) * k - (rect[2] - rect[0])) / grow;
+            }
         } else {
-            local[0] = f64::from(hx) * ((rect[3] - rect[1] + grow * f64::from(hy) * local[1]) * k - (rect[2] - rect[0])) / grow;
+            // A turned corner with a ratio slides along its turned diagonal, which crosses the
+            // guides at an angle: slide it onto the nearest line it reached. Moved sideways onto
+            // the line instead, the ratio (a ⇧ corner's diagonal) put it back off the line.
+            let along = [f64::from(hx) * k, f64::from(hy)];
+            let v = crate::crop_ui::turn(along, [0.0, 0.0], deg);
+            let slide = lines
+                .iter()
+                .filter_map(|line| {
+                    let (gap, step) = if line.vertical { (line.pos - handle[0], v[0]) } else { (line.pos - handle[1], v[1]) };
+                    (step.abs() > 1e-9).then(|| gap / step)
+                })
+                .min_by(|a, b| a.abs().total_cmp(&b.abs()));
+            let Some(s) = slide else { return Some((p, Vec::new())) };
+            local = [(travel[0] + s * along[0]) / scale, (travel[1] + s * along[1]) / scale];
         }
     }
     let d = crate::crop_ui::turn(local, [0.0, 0.0], deg);
diff --git a/crates/ui-egui/src/tools/crop_ui/tests.rs b/crates/ui-egui/src/tools/crop_ui/tests.rs
index 65b35c689a..d70e2f5792 100644
--- a/crates/ui-egui/src/tools/crop_ui/tests.rs
+++ b/crates/ui-egui/src/tools/crop_ui/tests.rs
@@ -406,6 +406,26 @@ fn handles_resize_with_shift_and_alt() {
     assert_eq!(app.ui.crop_rect, Some([40.0, 10.0, 100.0, 70.0]));
 }
 
+/// The top-right and bottom-left corners follow the other diagonal, (120, −50) and (−120, 50):
+/// the drag projected onto it grows the frame by 2200 / 16900, as on the top-left corner. Along
+/// the top-left / bottom-right diagonal the top-right x1 would move to about 141.4.
+#[test]
+fn shift_resize_follows_the_diagonal_of_the_top_right_and_bottom_left_corners() {
+    let mut app = app(SampleType::U8);
+    app.ui.crop_rect = Some([20.0, 20.0, 140.0, 70.0]);
+    drag(&mut app, &[[140.0, 20.0], [150.0, 0.0]], SHIFT);
+    let r = app.ui.crop_rect.unwrap();
+    assert_eq!((r[0], r[3]), (20.0, 70.0), "top-right: opposite corner fixed");
+    assert!((r[2] - (140.0 + 2640.0 / 169.0)).abs() < 1e-9, "top-right: {r:?}");
+    assert!((r[1] - (20.0 - 1100.0 / 169.0)).abs() < 1e-9, "top-right: {r:?}");
+    app.ui.crop_rect = Some([20.0, 20.0, 140.0, 70.0]);
+    drag(&mut app, &[[20.0, 70.0], [10.0, 90.0]], SHIFT);
+    let r = app.ui.crop_rect.unwrap();
+    assert_eq!((r[2], r[1]), (140.0, 20.0), "bottom-left: opposite corner fixed");
+    assert!((r[0] - (20.0 - 2640.0 / 169.0)).abs() < 1e-9, "bottom-left: {r:?}");
+    assert!((r[3] - (70.0 + 1100.0 / 169.0)).abs() < 1e-9, "bottom-left: {r:?}");
+}
+
 #[test]
 fn dragging_a_handle_past_the_other_side_flips_and_collapse_reverts() {
     let mut app = app(SampleType::U8);
diff --git a/crates/ui-egui/tests/it/crop_shift_corner.rs b/crates/ui-egui/tests/it/crop_shift_corner.rs
index e18e62bca8..55923aa134 100644
--- a/crates/ui-egui/tests/it/crop_shift_corner.rs
+++ b/crates/ui-egui/tests/it/crop_shift_corner.rs
@@ -73,6 +73,12 @@ fn commit(app: &mut PhotocraftApp) -> (u32, u32) {
 /// Drags the bottom-right corner by document vector `d` in steps through `ui.pointer`, holding
 /// `mods`, and commits.
 fn drag_corner_and_commit(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) -> (u32, u32) {
+    drag_corner(app, d, mods);
+    commit(app)
+}
+
+/// [`drag_corner_and_commit`] without the commit: the frame stays pending.
+fn drag_corner(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) {
     let [x, y] = corner(app);
     let mut events = vec![json!({"kind": "down", "x": x, "y": y})];
     events.extend((1..=4).map(|i| {
@@ -83,7 +89,6 @@ fn drag_corner_and_commit(app: &mut PhotocraftApp, d: [f64; 2], mods: Value) ->
     let mut params = mods;
     params["events"] = Value::Array(events);
     pointer(app, params);
-    commit(app)
 }
 
 fn assert_near(got: (u32, u32), want: (u32, u32), what: &str) {
@@ -178,3 +183,32 @@ fn a_shift_corner_drag_snaps_where_its_handle_is() {
         assert_near(got, want, &format!("⇧ drag with a guide at x = {guide}"));
     }
 }
+
+/// On a frame turned 30° the corner slides along the turned diagonal, direction (0.89, 1.67) for
+/// 8 : 5, so a vertical guide is met by sliding along it, not by moving the handle sideways.
+///
+/// - ⇧, free ratio: the measured drag leaves the handle at x ≈ 569.2, 4.2 px from a guide at
+///   x = 565. Sliding on to it shortens the frame by 12.7 % to 698.1 × 436.3. Moving the handle
+///   sideways and projecting that back onto the diagonal stopped it at x ≈ 568.3, off the guide,
+///   at 704 × 440.
+/// - An 8 : 5 preset (the larger extent wins, 720 × 450) leaves it at x ≈ 577.1, 4.1 px from a
+///   guide at x = 573: 712.5 × 445.3. Sideways, the larger extent grew the frame to 723 × 452,
+///   away from the guide.
+#[test]
+fn a_shift_corner_drag_on_a_turned_frame_snaps_along_its_diagonal() {
+    for (ratio, guide, want) in [("", 565.0, (698, 436)), ("8:5", 573.0, (712, 445))] {
+        for classic in [true, false] {
+            let what = format!("ratio {ratio:?}, guide at x = {guide}, Classic Mode {classic}");
+            let mut app = crop_app(Setup { classic, ratio, snap: true, ..Setup::default() });
+            app.ui.crop_angle = 30.0;
+            photocraft_ui_egui::crop_mode::sync_frame(&mut app);
+            app.run("view.newGuide", json!({"orientation": "vertical", "position": guide})).expect("guide");
+            drag_corner(&mut app, crop_ui::turn(DRAG, [0.0, 0.0], 30.0), json!({"shift": true}));
+            let at = corner(&app);
+            assert!((at[0] - guide).abs() < 1e-3, "{what}: the handle is at {at:?}, not on the guide");
+            let r = app.ui.crop_rect.expect("a frame");
+            assert!(((r[2] - r[0]) / (r[3] - r[1]) - 1.6).abs() < 1e-9, "{what}: 8 : 5 kept, {r:?}");
+            assert_near(commit(&mut app), want, &what);
+        }
+    }
+}

From 7cd9c9beb9a6c065ed20d540f066427e8f397e35 Mon Sep 17 00:00:00 2001
From: dotCooCoo <RobertLeeLW@gmail.com>
Date: Mon, 2 Nov 2026 19:56:03 -0800
Subject: [PATCH 083/109] Layers: test Artboard filtering with nested artboards

---
 .../src/panels/layer_filter_ui/tests.rs       | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
index 3e8be2f1a9..838450346b 100644
--- a/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
+++ b/crates/ui-egui/src/panels/layer_filter_ui/tests.rs
@@ -257,3 +257,29 @@ fn the_artboard_filter_walks_deep_groups_without_recursion() {
         .join()
         .unwrap();
 }
+
+#[test]
+fn the_artboard_filter_lists_the_outer_artboard_for_a_layer_in_a_nested_artboard() {
+    use photocraft_color::{ColorMode, SampleType};
+    use photocraft_doc::{Artboard, Group, Layer, LayerContent, Size};
+    use photocraft_geom::Rect;
+    use std::collections::HashSet;
+
+    fn group(name: &str, children: Vec<Layer>, artboard: Option<Artboard>) -> Layer {
+        Layer::new(name, LayerContent::Group(Group { children, expanded: true, artboard, frame_stroke: None }))
+    }
+    let leaf = group("Leaf", vec![], None);
+    let inner = group("Inner", vec![leaf.clone()], Some(Artboard::new(Rect::new(0, 0, 4, 4))));
+    let sibling = group("Sibling", vec![], None);
+    let outer = group("Outer", vec![inner.clone(), sibling.clone()], Some(Artboard::new(Rect::new(0, 0, 8, 8))));
+    let other = group("Other", vec![], Some(Artboard::new(Rect::new(8, 0, 8, 8))));
+    let mut doc = Document::new("Nested artboards", Size::new(16, 8), ColorMode::Rgb, SampleType::U8);
+    let (outer_id, inner_id, leaf_id, sibling_id, other_id) = (outer.id, inner.id, leaf.id, sibling.id, other.id);
+    doc.layers.push(outer);
+    doc.layers.push(other);
+    let outer_rows = HashSet::from([outer_id, inner_id, leaf_id, sibling_id]);
+    assert_eq!(super::board_rows(&doc, &[leaf_id]), outer_rows, "a layer in a nested artboard: the outer artboard's rows");
+    assert_eq!(super::board_rows(&doc, &[inner_id]), outer_rows, "the nested artboard itself: the outer artboard's rows");
+    let both: HashSet<_> = outer_rows.iter().copied().chain([other_id]).collect();
+    assert_eq!(super::board_rows(&doc, &[leaf_id, other_id]), both);
+}

From be5b361c592a48cfb4320821529ee60cf513d2ad Mon Sep 17 00:00:00 2001
From: ljkx <177671075+ljkx@users.noreply.github.com>
Date: Tue, 3 Nov 2026 05:53:10 +0100
Subject: [PATCH 084/109] Crop: a turned ratio corner snaps only to a crossing
 within reach

Sliding a turned ratio corner along its diagonal onto a guide went as far
as the crossing was: with the diagonal nearly parallel to the guide, a
guide a few px from the handle is met hundreds of px further along, and
the frame jumped there. The slide now has to stay inside the tolerance box
the handle was snapped in (at most the tolerance on each axis); otherwise
the corner follows the drag unsnapped.

Test: a frame turned -31 degrees, whose bottom-right diagonal runs 1 degree
off horizontal, ignores a horizontal guide 3 px from the handle and ends
as with no guide, in Classic Mode and the default mode. It grew by about
40 % before.
---
 crates/ui-egui/src/canvas/snap_ui.rs         |  4 +++
 crates/ui-egui/tests/it/crop_shift_corner.rs | 28 ++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/crates/ui-egui/src/canvas/snap_ui.rs b/crates/ui-egui/src/canvas/snap_ui.rs
index e360202fb1..8b3c6525a1 100644
--- a/crates/ui-egui/src/canvas/snap_ui.rs
+++ b/crates/ui-egui/src/canvas/snap_ui.rs
@@ -438,12 +438,16 @@ fn crop_handle(app: &PhotocraftApp, p: [f64; 2], mods: egui::Modifiers, targets:
             // the line instead, the ratio (a ⇧ corner's diagonal) put it back off the line.
             let along = [f64::from(hx) * k, f64::from(hy)];
             let v = crate::crop_ui::turn(along, [0.0, 0.0], deg);
+            // A diagonal nearly parallel to the line meets it far along: snap only to a crossing
+            // inside the tolerance box `snap_point` read the handle in (|s·v| ≤ tol on each axis).
+            let reach = tol / v[0].abs().max(v[1].abs());
             let slide = lines
                 .iter()
                 .filter_map(|line| {
                     let (gap, step) = if line.vertical { (line.pos - handle[0], v[0]) } else { (line.pos - handle[1], v[1]) };
                     (step.abs() > 1e-9).then(|| gap / step)
                 })
+                .filter(|s| s.abs() <= reach)
                 .min_by(|a, b| a.abs().total_cmp(&b.abs()));
             let Some(s) = slide else { return Some((p, Vec::new())) };
             local = [(travel[0] + s * along[0]) / scale, (travel[1] + s * along[1]) / scale];
diff --git a/crates/ui-egui/tests/it/crop_shift_corner.rs b/crates/ui-egui/tests/it/crop_shift_corner.rs
index 55923aa134..f7452b94cf 100644
--- a/crates/ui-egui/tests/it/crop_shift_corner.rs
+++ b/crates/ui-egui/tests/it/crop_shift_corner.rs
@@ -212,3 +212,31 @@ fn a_shift_corner_drag_on_a_turned_frame_snaps_along_its_diagonal() {
         }
     }
 }
+
+/// Turned 31° the other way, the 8 : 5 frame's bottom-right diagonal runs 1° off horizontal, so it
+/// crosses a horizontal guide 3 px from the handle about 170 px further along. That crossing is
+/// well outside the 8 px snap tolerance: the guide doesn't catch the handle and the frame follows
+/// the drag, as with no guide. Sliding to the crossing grew the frame by about 40 %.
+#[test]
+fn a_turned_shift_corner_ignores_a_guide_its_diagonal_meets_far_away() {
+    let drag = crop_ui::turn([-50.0, -25.0], [0.0, 0.0], -31.0);
+    for classic in [true, false] {
+        let what = format!("Classic Mode {classic}");
+        // Off the document's centre lines, which snap too.
+        let setup = || {
+            let mut app = crop_app(Setup { classic, snap: true, ..Setup::default() });
+            app.ui.crop_rect = Some([100.0, 60.0, 500.0, 310.0]);
+            app.ui.crop_angle = -31.0;
+            photocraft_ui_egui::crop_mode::sync_frame(&mut app);
+            app
+        };
+        let mut free = setup();
+        drag_corner(&mut free, drag, json!({"shift": true}));
+        let (want, at) = (free.ui.crop_rect.expect("a frame"), corner(&free));
+        let mut app = setup();
+        app.run("view.newGuide", json!({"orientation": "horizontal", "position": at[1] + 3.0})).expect("guide");
+        drag_corner(&mut app, drag, json!({"shift": true}));
+        let r = app.ui.crop_rect.expect("a frame");
+        assert!(r.iter().zip(want).all(|(a, b)| (a - b).abs() < 1e-6), "{what}: {r:?}, want {want:?} as with no guide");
+    }
+}

From 2bad5596289973bb2b568ae677ce8bb242cf7330 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 10:33:52 +0100
Subject: [PATCH 085/109] psd: copy source-backed channel and merged data
 through in short reads

A channel or merged image still in its source (an imported file's, or one
spilled to scratch) is copied to the output in 8 MiB pieces instead of being
read whole into memory first.
---
 crates/psd/src/file.rs  | 34 +++++++++++++++++++++++++++++++---
 crates/psd/src/io.rs    | 17 +++++++++++++++++
 crates/psd/src/layer.rs |  5 ++---
 3 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/crates/psd/src/file.rs b/crates/psd/src/file.rs
index 1e2c60f827..babcef4f58 100644
--- a/crates/psd/src/file.rs
+++ b/crates/psd/src/file.rs
@@ -382,10 +382,9 @@ impl PsdFile {
             o.put_u16(self.image_data.compression.as_u16());
             Ok(())
         })?;
-        let merged = self.image_data.encoded()?;
         match self.merged_widened_rows(widen)? {
-            0 => out.put(&merged),
-            rows => out.put_widened_rle(&merged, rows),
+            0 => out.put_encoded(&self.image_data.data, self.image_data.stored.as_ref()),
+            rows => out.put_widened_rle(&self.image_data.encoded()?, rows),
         }
     }
 
@@ -719,6 +718,35 @@ mod write_tests {
         }
     }
 
+    /// Channel data and a merged image still in their source (an imported file's, or what an
+    /// exporter spilled to scratch) are copied through in short reads, never read whole.
+    #[test]
+    fn source_backed_data_is_copied_in_short_reads() {
+        struct Reads(Vec<u8>, std::sync::Mutex<usize>);
+        impl crate::source::ReadAt for Reads {
+            fn len(&self) -> u64 {
+                self.0.len() as u64
+            }
+            fn read_at(&self, offset: u64, buf: &mut [u8]) -> Result<()> {
+                let mut most = self.1.lock().unwrap();
+                *most = (*most).max(buf.len());
+                self.0.as_slice().read_at(offset, buf)
+            }
+        }
+        let mut file = testgen::small(Version::Psd, Compression::Raw);
+        file.image_data = ImageData::new(Compression::Raw, vec![5; 300]);
+        let info = file.layer_info.as_mut().unwrap();
+        info.layers[0].channels[0] = crate::layer::ChannelData::new(0, Some(Compression::Raw), vec![6; 301]);
+        let bytes = file.to_bytes().unwrap();
+        let source = std::sync::Arc::new(Reads(bytes.clone(), std::sync::Mutex::new(0)));
+        let lazy = PsdFile::from_source(crate::Source::from_arc(source.clone())).unwrap();
+        *source.1.lock().unwrap() = 0;
+        let mut w = std::io::Cursor::new(Vec::new());
+        lazy.write_to(&mut w).unwrap();
+        assert!(w.into_inner() == bytes);
+        assert!(*source.1.lock().unwrap() <= 7, "read {} bytes at once", source.1.lock().unwrap());
+    }
+
     /// #6607: pixel data goes to the stream as it is, never through a staging copy, so a save
     /// holds the model and a short buffer, not a second copy of the file.
     #[test]
diff --git a/crates/psd/src/io.rs b/crates/psd/src/io.rs
index eb7185bde2..bf4468711a 100644
--- a/crates/psd/src/io.rs
+++ b/crates/psd/src/io.rs
@@ -213,6 +213,8 @@ impl WriteExt for Vec<u8> {
 
 /// Staged bytes [`Sink`] collects before writing them out in one call.
 const STAGE: usize = 64 << 10;
+/// Bytes of stored channel data read per piece by [`Sink::put_encoded`].
+const COPY_CHUNK: u64 = if cfg!(test) { 7 } else { 8 << 20 };
 #[cfg(test)]
 pub(crate) const STAGE_FOR_TESTS: usize = STAGE;
 
@@ -283,6 +285,21 @@ impl<'w, W: Write + Seek + ?Sized> Sink<'w, W> {
         self.put(packed)
     }
 
+    /// Appends encoded bytes held in memory (`data`) or, when `stored`, still in their source:
+    /// those are copied through in [`COPY_CHUNK`] pieces, so a channel or merged image kept on
+    /// disk (an imported file's, or one an exporter spilled to scratch) is never read whole.
+    pub(crate) fn put_encoded(&mut self, data: &[u8], stored: Option<&crate::source::Stored>) -> std::io::Result<()> {
+        let Some(s) = stored else { return self.put(data) };
+        let mut at = 0u64;
+        while at < s.len {
+            let n = (s.len - at).min(COPY_CHUNK);
+            let part = s.read_part(at, n)?;
+            self.put(&part)?;
+            at += n;
+        }
+        Ok(())
+    }
+
     /// `n` zero bytes (padding, at most a few).
     pub(crate) fn zeros(&mut self, n: usize) -> std::io::Result<()> {
         self.small(|b| {
diff --git a/crates/psd/src/layer.rs b/crates/psd/src/layer.rs
index fc1a3ff571..3b492e6a04 100644
--- a/crates/psd/src/layer.rs
+++ b/crates/psd/src/layer.rs
@@ -858,10 +858,9 @@ impl LayerInfo {
                         o.put_u16(comp.as_u16());
                         Ok(())
                     })?;
-                    let data = c.encoded()?;
                     match l.widened_rows(c, widen)? {
-                        0 => out.put(&data)?,
-                        rows => out.put_widened_rle(&data, rows)?,
+                        0 => out.put_encoded(&c.data, c.stored.as_ref())?,
+                        rows => out.put_widened_rle(&c.encoded()?, rows)?,
                     }
                 }
             }

From 4b27da939f7d70f614e72fa03517c3bc8efaecf3 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 10:49:38 +0100
Subject: [PATCH 086/109] raster: anonymous append-only stage file on the
 scratch disk

Shares ScratchFile's private open (0600, unlinked at once, delete-on-close on
Windows) so encoded save data can be parked off the heap and read back by offset.
---
 crates/raster/src/lib.rs          |   1 +
 crates/raster/src/scratch_file.rs |  81 ++++++++++++---------
 crates/raster/src/stage_file.rs   | 112 ++++++++++++++++++++++++++++++
 3 files changed, 160 insertions(+), 34 deletions(-)
 create mode 100644 crates/raster/src/stage_file.rs

diff --git a/crates/raster/src/lib.rs b/crates/raster/src/lib.rs
index 994c02c57c..77121d0e7d 100644
--- a/crates/raster/src/lib.rs
+++ b/crates/raster/src/lib.rs
@@ -49,6 +49,7 @@ impl std::error::Error for AllocationError {}
 pub mod memory;
 mod scratch_file;
 pub mod spill;
+pub mod stage_file;
 
 /// One shared tile per pixel value (and tile size), for [`Surface::share_uniform_tiles`].
 #[derive(Debug, Default)]
diff --git a/crates/raster/src/scratch_file.rs b/crates/raster/src/scratch_file.rs
index bcb46c3d0f..fc131543b4 100644
--- a/crates/raster/src/scratch_file.rs
+++ b/crates/raster/src/scratch_file.rs
@@ -118,35 +118,9 @@ impl std::fmt::Debug for ScratchFile {
 
 impl ScratchFile {
     pub fn create(dir: &Path) -> std::io::Result<Self> {
-        std::fs::create_dir_all(dir)?;
-        static COUNTER: AtomicUsize = AtomicUsize::new(0);
-        // A reused process id must not collide with an abandoned file from an older launch.
-        let n = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap_or_default()
-            .as_nanos()
-            .saturating_add(COUNTER.fetch_add(1, Ordering::Relaxed) as u128);
-        let path = dir.join(format!("photocraft-{}-{n}.scratch", std::process::id()));
-        let mut options = std::fs::OpenOptions::new();
-        options.read(true).write(true).create_new(true);
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::OpenOptionsExt;
-            options.mode(0o600);
-        }
+        let (main, path, linked) = open_private(dir)?;
         #[cfg(windows)]
-        {
-            use std::os::windows::fs::OpenOptionsExt;
-            const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x0400_0000;
-            options.custom_flags(FILE_FLAG_DELETE_ON_CLOSE);
-        }
-        let main = options.open(&path)?;
-        #[cfg(unix)]
-        reap_abandoned(dir, &main);
-        // Unix: the open handle keeps the inode; nothing is left behind at any exit. A
-        // filesystem that refuses the unlink keeps the name until drop or the next reap.
-        #[cfg(not(windows))]
-        let linked = std::fs::remove_file(&path).is_err();
+        let _ = linked;
         Ok(Self {
             main,
             #[cfg(windows)]
@@ -231,6 +205,45 @@ impl ScratchFile {
     }
 }
 
+/// Creates a file only this process can reach in `dir`, gone once its last handle closes: Unix
+/// opens it private (0600) and unlinks it right away, Windows opens it delete-on-close. Files
+/// of dead processes are reaped. Returns the file, its name, and whether the name is still
+/// there (a filesystem refused the unlink: remove it when done).
+pub(crate) fn open_private(dir: &Path) -> std::io::Result<(File, PathBuf, bool)> {
+    std::fs::create_dir_all(dir)?;
+    static COUNTER: AtomicUsize = AtomicUsize::new(0);
+    // A reused process id must not collide with an abandoned file from an older launch.
+    let n = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_nanos()
+        .saturating_add(COUNTER.fetch_add(1, Ordering::Relaxed) as u128);
+    let path = dir.join(format!("photocraft-{}-{n}.scratch", std::process::id()));
+    let mut options = std::fs::OpenOptions::new();
+    options.read(true).write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::OpenOptionsExt;
+        const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x0400_0000;
+        options.custom_flags(FILE_FLAG_DELETE_ON_CLOSE);
+    }
+    let file = options.open(&path)?;
+    #[cfg(unix)]
+    reap_abandoned(dir, &file);
+    // Unix: the open handle keeps the inode; nothing is left behind at any exit. A
+    // filesystem that refuses the unlink keeps the name until drop or the next reap.
+    #[cfg(not(windows))]
+    let linked = std::fs::remove_file(&path).is_err();
+    #[cfg(windows)]
+    let linked = false;
+    Ok((file, path, linked))
+}
+
 /// Accept only the names we generate, never other temporary files or directories.
 #[cfg(any(unix, test))]
 fn scratch_pid(name: &str) -> Option<u32> {
@@ -297,17 +310,17 @@ fn thread_slot() -> usize {
 }
 
 #[cfg(unix)]
-fn write_all_at(file: &File, data: &[u8], offset: u64) -> std::io::Result<()> {
+pub(crate) fn write_all_at(file: &File, data: &[u8], offset: u64) -> std::io::Result<()> {
     std::os::unix::fs::FileExt::write_all_at(file, data, offset)
 }
 
 #[cfg(unix)]
-fn read_exact_at(file: &File, buf: &mut [u8], offset: u64) -> std::io::Result<()> {
+pub(crate) fn read_exact_at(file: &File, buf: &mut [u8], offset: u64) -> std::io::Result<()> {
     std::os::unix::fs::FileExt::read_exact_at(file, buf, offset)
 }
 
 #[cfg(windows)]
-fn write_all_at(file: &File, mut data: &[u8], mut offset: u64) -> std::io::Result<()> {
+pub(crate) fn write_all_at(file: &File, mut data: &[u8], mut offset: u64) -> std::io::Result<()> {
     use std::os::windows::fs::FileExt;
     while !data.is_empty() {
         let n = file.seek_write(data, offset)?;
@@ -321,7 +334,7 @@ fn write_all_at(file: &File, mut data: &[u8], mut offset: u64) -> std::io::Resul
 }
 
 #[cfg(windows)]
-fn read_exact_at(file: &File, mut buf: &mut [u8], mut offset: u64) -> std::io::Result<()> {
+pub(crate) fn read_exact_at(file: &File, mut buf: &mut [u8], mut offset: u64) -> std::io::Result<()> {
     use std::os::windows::fs::FileExt;
     while !buf.is_empty() {
         let n = file.seek_read(buf, offset)?;
@@ -335,12 +348,12 @@ fn read_exact_at(file: &File, mut buf: &mut [u8], mut offset: u64) -> std::io::R
 }
 
 #[cfg(not(any(unix, windows)))]
-fn write_all_at(_file: &File, _data: &[u8], _offset: u64) -> std::io::Result<()> {
+pub(crate) fn write_all_at(_file: &File, _data: &[u8], _offset: u64) -> std::io::Result<()> {
     Err(std::io::ErrorKind::Unsupported.into())
 }
 
 #[cfg(not(any(unix, windows)))]
-fn read_exact_at(_file: &File, _buf: &mut [u8], _offset: u64) -> std::io::Result<()> {
+pub(crate) fn read_exact_at(_file: &File, _buf: &mut [u8], _offset: u64) -> std::io::Result<()> {
     Err(std::io::ErrorKind::Unsupported.into())
 }
 
diff --git a/crates/raster/src/stage_file.rs b/crates/raster/src/stage_file.rs
new file mode 100644
index 0000000000..e371fbe6be
--- /dev/null
+++ b/crates/raster/src/stage_file.rs
@@ -0,0 +1,112 @@
+//! Encoded data an exporter parks on the scratch disk instead of in memory (#5333).
+//!
+//! A large PSD/PSB save encodes every channel before it writes a byte (so it can still be
+//! cancelled, and its scratch reads are checked, before the file is replaced). Kept in memory,
+//! those channels are a second copy of the document. A [`StageFile`] holds them on the scratch
+//! disk instead: an append-only file made like the tile scratch file (private, unlinked on Unix,
+//! delete-on-close on Windows), so nothing is left behind at any exit, and the space returns as
+//! soon as the save drops it.
+
+use std::fs::File;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, PoisonError};
+
+use crate::scratch_file::{open_private, read_exact_at, write_all_at};
+
+pub struct StageFile {
+    file: File,
+    path: PathBuf,
+    /// The directory entry still exists (the unlink was refused): remove it on drop.
+    linked: bool,
+    /// Bytes reserved so far; appends take their offset from it.
+    end: Mutex<u64>,
+}
+
+impl std::fmt::Debug for StageFile {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StageFile").field("path", &self.path).field("len", &self.len()).finish()
+    }
+}
+
+impl StageFile {
+    /// A new, empty stage file in `dir`.
+    pub fn create(dir: &Path) -> std::io::Result<Self> {
+        let (file, path, linked) = open_private(dir)?;
+        Ok(Self { file, path, linked, end: Mutex::new(0) })
+    }
+
+    /// A stage file in the configured scratch directory, when spilling is on (`None` otherwise,
+    /// or when the file cannot be made: the caller then keeps its data in memory).
+    pub fn in_scratch() -> Option<Self> {
+        if !crate::spill::enabled() {
+            return None;
+        }
+        Self::create(&crate::spill::stats().dir?).ok()
+    }
+
+    /// Appends `data` and returns its offset. Parallel appends each get their own range.
+    pub fn append(&self, data: &[u8]) -> std::io::Result<u64> {
+        let offset = {
+            let mut end = self.end.lock().unwrap_or_else(PoisonError::into_inner);
+            let offset = *end;
+            *end = offset.checked_add(data.len() as u64).ok_or_else(|| std::io::Error::other("stage file too large"))?;
+            offset
+        };
+        write_all_at(&self.file, data, offset)?;
+        Ok(offset)
+    }
+
+    /// Fills `buf` from `offset`, which must lie within what was appended.
+    pub fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> std::io::Result<()> {
+        if offset.checked_add(buf.len() as u64).is_none_or(|end| end > self.len()) {
+            return Err(std::io::ErrorKind::UnexpectedEof.into());
+        }
+        read_exact_at(&self.file, buf, offset)
+    }
+
+    /// Bytes appended (reserved) so far.
+    pub fn len(&self) -> u64 {
+        *self.end.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+}
+
+impl Drop for StageFile {
+    fn drop(&mut self) {
+        if self.linked {
+            let _ = std::fs::remove_file(&self.path);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn appends_read_back_and_leave_nothing_behind() {
+        let dir = std::env::temp_dir().join(format!("pc-stage-{}", std::process::id()));
+        let stage = StageFile::create(&dir).unwrap();
+        #[cfg(unix)]
+        assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0, "the stage file is unlinked while open");
+        let parts: Vec<Vec<u8>> = (0..8u8).map(|i| vec![i; 1000 + usize::from(i)]).collect();
+        let offsets: Vec<u64> = std::thread::scope(|s| {
+            let handles: Vec<_> = parts.iter().map(|p| s.spawn(|| stage.append(p).unwrap())).collect();
+            handles.into_iter().map(|h| h.join().unwrap()).collect()
+        });
+        assert_eq!(stage.len(), parts.iter().map(|p| p.len() as u64).sum::<u64>());
+        for (p, &at) in parts.iter().zip(&offsets) {
+            let mut buf = vec![0; p.len()];
+            stage.read_exact_at(&mut buf, at).unwrap();
+            assert_eq!(&buf, p);
+        }
+        let mut past = [0u8; 2];
+        assert!(stage.read_exact_at(&mut past, stage.len() - 1).is_err(), "reads stop at what was appended");
+        drop(stage);
+        assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0);
+        let _ = std::fs::remove_dir(&dir);
+    }
+}

From dbcee2ba476d694b5e59ecdd5324f4dd709dfbac Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 10:49:38 +0100
Subject: [PATCH 087/109] io: stage encoded PSD/PSB channels on the scratch
 disk for large saves

Each colour channel and the merged image is parked in a scratch stage file as
soon as it is encoded (documents of 1 GiB+ raw pixels, chunks of 64 KiB+), so a
save no longer holds every encoded plane in memory before #8115's checked write.
The written file is byte-identical; when staging is unavailable the data stays
in memory.
---
 crates/io/src/lib.rs                 |   1 +
 crates/io/src/psd_export.rs          |  17 ++++-
 crates/io/src/psd_export/document.rs |   8 +++
 crates/io/src/psd_export/stage.rs    | 103 +++++++++++++++++++++++++++
 crates/io/src/psd_export/tests.rs    |  53 ++++++++++++++
 crates/io/src/tiff_layers.rs         |   2 +
 6 files changed, 182 insertions(+), 2 deletions(-)
 create mode 100644 crates/io/src/psd_export/stage.rs

diff --git a/crates/io/src/lib.rs b/crates/io/src/lib.rs
index 2d4371d4c1..f976867778 100644
--- a/crates/io/src/lib.rs
+++ b/crates/io/src/lib.rs
@@ -793,6 +793,7 @@ fn export_stages(doc: &Document, name_or_ext: &str, opts: &ExportOptions, ctl: &
             maximize_compatibility: opts.psd_maximize_compatibility,
             document_path: opts.document_path.clone(),
             read_linked_files: opts.read_linked_files,
+            stage_on_scratch_from: Some(psd_export::STAGE_DOCUMENTS_FROM),
             ..Default::default()
         };
         // The preview is rendered first, while only the document is in memory: its full-size
diff --git a/crates/io/src/psd_export.rs b/crates/io/src/psd_export.rs
index 6086aaf644..6f87aa7588 100644
--- a/crates/io/src/psd_export.rs
+++ b/crates/io/src/psd_export.rs
@@ -20,6 +20,8 @@ mod estimate;
 mod merged;
 mod resources;
 mod smart;
+mod stage;
+pub(crate) use stage::STAGE_DOCUMENTS_FROM;
 
 pub(crate) use document::document_to_psd_interruptible;
 #[cfg(test)]
@@ -74,6 +76,10 @@ pub struct PsdExportOptions {
     /// off, since a stored path is document data rather than a granted file: such a layer is
     /// then written as pixels, with a warning.
     pub read_linked_files: bool,
+    /// Park each encoded channel on the scratch disk, not in memory, when the document's raw
+    /// pixel bytes (layers and composite) reach this and spilling is on (`None`: never). The
+    /// save then holds the file model's structure, not a second copy of its pixels (#5333).
+    pub stage_on_scratch_from: Option<u64>,
 }
 
 impl Default for PsdExportOptions {
@@ -86,6 +92,7 @@ impl Default for PsdExportOptions {
             maximize_compatibility: true,
             document_path: None,
             read_linked_files: true,
+            stage_on_scratch_from: None,
         }
     }
 }
@@ -126,6 +133,8 @@ struct Ex {
     patterns: Vec<photocraft_doc::Pattern>,
     /// The layer written as Photoshop's Background (see [`psd_background`]).
     background: Option<photocraft_doc::LayerId>,
+    /// Where encoded channels go instead of memory ([`PsdExportOptions::stage_on_scratch_from`]).
+    stage: Option<std::sync::Arc<stage::Stage>>,
 }
 
 /// The layer Photoshop should open as its Background: the bottom top-level layer when it is a
@@ -186,9 +195,13 @@ impl Ex {
         // A ZIP stream for a zero-sized channel makes readers try to decompress an
         // invalid image extent (notably psd-tools for 32-bit adjustment layers).
         let compression = if w == 0 || h == 0 { Compression::Raw } else { self.compression() };
-        ChannelData::encode(id, compression, plane, w, h, depth, self.version)
+        let c = ChannelData::encode(id, compression, plane, w, h, depth, self.version)
             .or_else(|_| ChannelData::encode(id, Compression::Raw, plane, w, h, depth, self.version))
-            .unwrap_or(ChannelData::new(id, Some(Compression::Raw), plane.to_vec()))
+            .unwrap_or(ChannelData::new(id, Some(Compression::Raw), plane.to_vec()));
+        match &self.stage {
+            Some(stage) => stage.channel(c),
+            None => c,
+        }
     }
 
     fn empty_channels(&self) -> Vec<ChannelData> {
diff --git a/crates/io/src/psd_export/document.rs b/crates/io/src/psd_export/document.rs
index f6c36c2d42..a87ed93010 100644
--- a/crates/io/src/psd_export/document.rs
+++ b/crates/io/src/psd_export/document.rs
@@ -88,6 +88,10 @@ fn export_supported_document(
         smart: SmartOut::new(doc, depth),
         patterns: doc.patterns.clone(),
         background: psd_background(doc),
+        stage: {
+            let raw = doc.size.area().saturating_mul(fmt.bytes_per_pixel() as u64).saturating_mul(doc.walk().len() as u64 + 1);
+            super::stage::Stage::for_document(raw, opts.stage_on_scratch_from)
+        },
     };
     add_format_warnings(doc, opts, fmt, big, duotone_inks.is_some(), &mut ex.warnings);
     index_layer_ids_and_text(doc, &mut ex);
@@ -331,6 +335,10 @@ fn prepare_merged_planes<'a>(
         data: planes,
         stored: None,
     });
+    let image_data = match &ex.stage {
+        Some(stage) => stage.image(image_data),
+        None => image_data,
+    };
     ctl.progress(1.0);
     MergedExport { header, image_data, extra, has_alpha, quick_mask_id, real_merged }
 }
diff --git a/crates/io/src/psd_export/stage.rs b/crates/io/src/psd_export/stage.rs
new file mode 100644
index 0000000000..3e04d53247
--- /dev/null
+++ b/crates/io/src/psd_export/stage.rs
@@ -0,0 +1,103 @@
+//! Encoded channels parked on the scratch disk while a large PSD/PSB save is assembled (#5333).
+//!
+//! A save encodes the whole file model before it writes a byte (#8115: it can still be
+//! cancelled, and the scratch reads behind it are checked, before the file is replaced). In
+//! memory that model is a second, compressed copy of every layer. With
+//! [`PsdExportOptions::stage_on_scratch_from`](super::PsdExportOptions::stage_on_scratch_from)
+//! set and spilling on, each channel is appended to a [`StageFile`] in the scratch directory as
+//! soon as it is encoded, and the model keeps only a [`Stored`] range: the writer then copies it
+//! through in short reads (`photocraft_psd`'s `put_encoded`). A channel that cannot be staged
+//! (the disk is full, say) stays in memory: staging only ever saves memory.
+
+use std::sync::Arc;
+
+use photocraft_psd::source::{ReadAt, Source, Stored};
+use photocraft_psd::{ChannelData, ImageData, PsdError};
+use photocraft_raster::stage_file::StageFile;
+
+/// Encoded data shorter than this stays in memory: a range costs more than it saves.
+const MIN_STAGED_BYTES: usize = 64 << 10;
+/// Raw pixel bytes (layers and composite, as sampled) from which a save made by
+/// [`crate::export_with`] stages its channels: about a 24 MP RGBA/16 document with five layers.
+pub(crate) const STAGE_DOCUMENTS_FROM: u64 = 1 << 30;
+
+#[cfg(test)]
+thread_local! {
+    /// Where this thread's exports stage, instead of the process-wide scratch directory.
+    pub(crate) static DIR_FOR_TESTS: std::cell::RefCell<Option<std::path::PathBuf>> = const { std::cell::RefCell::new(None) };
+}
+
+struct Backing(StageFile);
+
+impl ReadAt for Backing {
+    fn len(&self) -> u64 {
+        self.0.len()
+    }
+
+    fn read_at(&self, offset: u64, buf: &mut [u8]) -> photocraft_psd::Result<()> {
+        self.0.read_exact_at(buf, offset).map_err(|e| PsdError::Read(format!("staged export data, {} bytes at offset {offset}: {e}", buf.len())))
+    }
+}
+
+/// The stage of one export: a file on the scratch disk shared by every channel.
+pub(crate) struct Stage {
+    file: Arc<Backing>,
+    source: Source,
+}
+
+impl Stage {
+    /// A stage for a document of `raw_bytes` pixel bytes, when `from` asks for one at that size
+    /// and a stage file can be made in the scratch directory.
+    pub(crate) fn for_document(raw_bytes: u64, from: Option<u64>) -> Option<Arc<Self>> {
+        if raw_bytes < from? {
+            return None;
+        }
+        #[cfg(test)]
+        if let Some(dir) = DIR_FOR_TESTS.with(|d| d.borrow().clone()) {
+            return StageFile::create(&dir).ok().map(Self::new);
+        }
+        StageFile::in_scratch().map(Self::new)
+    }
+
+    fn new(file: StageFile) -> Arc<Self> {
+        let file = Arc::new(Backing(file));
+        let source = Source::from_arc(file.clone());
+        Arc::new(Self { file, source })
+    }
+
+    /// Moves `data` to the stage; `None` (the data kept by the caller) when it is short or the
+    /// write fails.
+    fn park(&self, data: &[u8]) -> Option<Stored> {
+        if data.len() < MIN_STAGED_BYTES {
+            return None;
+        }
+        let offset = self.file.0.append(data).ok()?;
+        Some(Stored { source: self.source.clone(), offset, len: data.len() as u64 })
+    }
+
+    pub(crate) fn channel(&self, mut c: ChannelData) -> ChannelData {
+        if c.stored.is_none()
+            && let Some(stored) = self.park(&c.data)
+        {
+            c.data = Vec::new();
+            c.stored = Some(stored);
+        }
+        c
+    }
+
+    pub(crate) fn image(&self, mut image: ImageData) -> ImageData {
+        if image.stored.is_none()
+            && let Some(stored) = self.park(&image.data)
+        {
+            image.data = Vec::new();
+            image.stored = Some(stored);
+        }
+        image
+    }
+
+    /// Bytes on the scratch disk.
+    #[cfg(test)]
+    pub(crate) fn len(&self) -> u64 {
+        self.file.0.len()
+    }
+}
diff --git a/crates/io/src/psd_export/tests.rs b/crates/io/src/psd_export/tests.rs
index c53f2c06f3..4fd78e8c73 100644
--- a/crates/io/src/psd_export/tests.rs
+++ b/crates/io/src/psd_export/tests.rs
@@ -619,3 +619,56 @@ fn a_linked_fifo_is_not_read() {
     let _ = std::fs::remove_dir_all(&dir);
     assert!(warnings.iter().any(|w| w.contains("smart object written as pixels") && w.contains("not a regular file")), "{warnings:?}");
 }
+
+/// #5333: with staging on, every large encoded channel and the merged image are parked on the
+/// scratch disk as they are encoded, and the file written from that model is the same, byte for
+/// byte, as one assembled in memory: as PSD, as PSB, and as a PSD promoted to PSB on the way out.
+#[test]
+fn staged_channels_write_the_same_file_as_in_memory_ones() {
+    let dir = std::env::temp_dir().join(format!("pc-psd-stage-{}", std::process::id()));
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = Some(dir.clone()));
+    let doc = sized_document(true, SampleType::U8);
+    let ctl = Interrupt::NONE;
+    for (force_psb, limit) in [(false, PSD_MAX_FILE_SIZE), (true, PSD_MAX_FILE_SIZE), (false, SIZED_LIMIT)] {
+        let plain = PsdExportOptions { force_psb, ..Default::default() };
+        let staged = PsdExportOptions { stage_on_scratch_from: Some(0), ..plain.clone() };
+        let (want, _) = document_to_psd_sized(&doc, &plain, 0, &ctl, limit);
+        let (file, _) = document_to_psd_sized(&doc, &staged, 0, &ctl, limit);
+        let layer = &file.layers()[0];
+        // The opaque alpha packs to a few KB and stays in memory; the noise colour channels go.
+        assert!(layer.channels.iter().filter(|c| c.id >= 0).all(|c| c.stored.is_some() && c.data.is_empty()), "every noise channel is staged");
+        assert!(layer.channels.iter().filter(|c| c.id == -1).all(|c| c.stored.is_none()), "the short alpha stays in memory");
+        assert!(file.image_data.stored.is_some() && file.image_data.data.is_empty(), "the merged image is staged");
+        assert_eq!(file.write_as_psb, want.write_as_psb);
+        let bytes = want.to_bytes().unwrap();
+        assert!(file.to_bytes().unwrap() == bytes, "psb {force_psb}, limit {limit}: staged bytes differ");
+        let mut w = std::io::Cursor::new(Vec::new());
+        file.write_to(&mut w).unwrap();
+        assert!(w.into_inner() == bytes, "psb {force_psb}, limit {limit}: streamed staged bytes differ");
+    }
+    // Under the threshold, or with no stage asked for, nothing is staged.
+    let (file, _) = document_to_psd_sized(&doc, &PsdExportOptions { stage_on_scratch_from: Some(u64::MAX), ..Default::default() }, 0, &ctl, PSD_MAX_FILE_SIZE);
+    assert!(file.layers()[0].channels.iter().all(|c| c.stored.is_none()) && file.image_data.stored.is_none());
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
+    #[cfg(unix)]
+    assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0, "the stage file has no name on disk");
+    let _ = std::fs::remove_dir(&dir);
+}
+
+/// Short channels stay in memory, and a stage that cannot be written keeps the data in memory.
+#[test]
+fn staging_keeps_short_or_unwritable_data_in_memory() {
+    let dir = std::env::temp_dir().join(format!("pc-psd-stage-short-{}", std::process::id()));
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = Some(dir.clone()));
+    let stage = stage::Stage::for_document(1, Some(0)).unwrap();
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
+    let short = stage.channel(ChannelData::new(0, Some(Compression::Raw), vec![1; 100]));
+    assert!(short.stored.is_none() && short.data.len() == 100);
+    let long = stage.channel(ChannelData::new(0, Some(Compression::Raw), vec![2; 1 << 17]));
+    assert!(long.stored.is_some() && long.data.is_empty());
+    assert_eq!(long.encoded().unwrap().as_ref(), &vec![2u8; 1 << 17][..]);
+    assert_eq!(stage.len(), 1 << 17);
+    assert!(stage::Stage::for_document(10, Some(11)).is_none(), "under the threshold");
+    assert!(stage::Stage::for_document(10, None).is_none(), "not asked for");
+    let _ = std::fs::remove_dir(&dir);
+}
diff --git a/crates/io/src/tiff_layers.rs b/crates/io/src/tiff_layers.rs
index f001b6a265..f0bb148179 100644
--- a/crates/io/src/tiff_layers.rs
+++ b/crates/io/src/tiff_layers.rs
@@ -265,6 +265,8 @@ pub(crate) fn export_layered(doc: &Document, opts: &ExportOptions, ctl: &photocr
         maximize_compatibility: true,
         document_path: opts.document_path.clone(),
         read_linked_files: opts.read_linked_files,
+        // The layered TIFF reads the merged image's bytes directly: they stay in memory.
+        stage_on_scratch_from: None,
     };
     // TIFF has no palette, bitmap or duotone layout: the PSD model of an Indexed Color, Bitmap
     // or Duotone document is made in its pixel format (RGB or Grayscale), which the PSD exporter

From d1f112c38ee6f8fe291a98e0e1e2a4d31bc7d2a0 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 10:49:38 +0100
Subject: [PATCH 088/109] automation: stream workspace saves instead of
 buffering the encoded file

AuthorizedWorkspace::write_stream keeps write()'s refusals and atomic replace but
lets the encoder write (and seek back) straight into the temp file, so an
automation PSB save no longer builds the whole file in a Vec.
---
 apps/photocraft/src/services.rs          |  2 +-
 crates/automation/src/workspace.rs       |  9 ++++++-
 crates/automation/src/workspace/tests.rs | 30 ++++++++++++++++++++++++
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/apps/photocraft/src/services.rs b/apps/photocraft/src/services.rs
index d9ddcf64d8..7741a8d8a3 100644
--- a/apps/photocraft/src/services.rs
+++ b/apps/photocraft/src/services.rs
@@ -685,7 +685,7 @@ pub fn native(automation: Option<photocraft_automation::AuthorizedWorkspace>) ->
     });
     let automation_save = automation.clone().map(|workspace| {
         std::sync::Arc::new(move |doc: &Document, path: &str, settings: &photocraft_ui_egui::ExportSettings, ctl: &photocraft_ui_egui::jobs_ui::SaveCtl| {
-            save_through(doc, path, settings, ctl, |p, encoded, _| workspace.write(p, &encoded.bytes().map_err(|e| e.to_string())?).map_err(|e| e.to_string()))
+            save_through(doc, path, settings, ctl, |p, encoded, _| workspace.write_stream(p, &mut |w| encoded.write_to(w)).map_err(|e| e.to_string()))
         }) as photocraft_ui_egui::SaveFileFn
     });
     let step: fn(&str, &serde_json::Value) -> photocraft_engine::Result<()> = photocraft_automation::workspace::authorize_desktop_engine_step;
diff --git a/crates/automation/src/workspace.rs b/crates/automation/src/workspace.rs
index a60cc66a16..d288f42f61 100644
--- a/crates/automation/src/workspace.rs
+++ b/crates/automation/src/workspace.rs
@@ -87,6 +87,13 @@ impl AuthorizedWorkspace {
     /// resolution and file creation relative to the held directory handle, so
     /// a non-existent final target is supported without ambient path access.
     pub fn write(&self, path: &str, bytes: &[u8]) -> Result<(), AutomationError> {
+        self.write_stream(path, &mut |w| w.write_all(bytes))
+    }
+
+    /// [`Self::write`] with the file's bytes produced by `write` straight into the temporary
+    /// file (it may seek back to patch lengths), so a large PSD/PSB is never held in memory
+    /// whole (#5333). The same refusals, the same atomic replace.
+    pub fn write_stream(&self, path: &str, write: &mut photocraft_format::atomic::StreamWriter<'_>) -> Result<(), AutomationError> {
         let relative = request_path(path, self.write.as_ref())?;
         let root = self.write.as_ref().ok_or_else(|| AutomationError::BadRequest(format!("{DENIED}: write authority is absent")))?;
         let leaf = relative.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
@@ -112,7 +119,7 @@ impl AuthorizedWorkspace {
         options.write(true).create_new(true);
         let written = root.dir.open_with(&tmp, &options).and_then(|file| {
             let mut file = file.into_std();
-            file.write_all(bytes)?;
+            write(&mut file)?;
             #[cfg(unix)]
             {
                 use std::os::fd::AsFd;
diff --git a/crates/automation/src/workspace/tests.rs b/crates/automation/src/workspace/tests.rs
index e96ccb369d..d44f984ece 100644
--- a/crates/automation/src/workspace/tests.rs
+++ b/crates/automation/src/workspace/tests.rs
@@ -122,6 +122,36 @@ fn write_replaces_atomically_and_leaves_no_temp_file() {
     assert!(temp_files(&inside).is_empty());
 }
 
+/// #5333: a streamed write (a PSD/PSB serialized as it goes, lengths patched by seeking back)
+/// replaces the file the same way; a writer that fails leaves the original and no temp file.
+#[test]
+fn write_stream_seeks_back_and_keeps_the_original_on_failure() {
+    use std::io::SeekFrom;
+    let (inside, _, workspace) = roots("stream");
+    workspace.write("big.psb", b"original").unwrap();
+    workspace
+        .write_stream("big.psb", &mut |w| {
+            w.write_all(b"....body")?;
+            w.seek(SeekFrom::Start(0))?;
+            w.write_all(b"head")?;
+            w.seek(SeekFrom::End(0))?;
+            Ok(())
+        })
+        .unwrap();
+    assert_eq!(std::fs::read(inside.join("big.psb")).unwrap(), b"headbody");
+    let failed = workspace.write_stream("big.psb", &mut |w| {
+        w.write_all(b"partial")?;
+        Err(std::io::Error::other("encoder failed"))
+    });
+    assert!(failed.is_err());
+    assert_eq!(std::fs::read(inside.join("big.psb")).unwrap(), b"headbody");
+    assert!(temp_files(&inside).is_empty());
+    // The same refusals as a plain write.
+    std::fs::write(inside.join("notes.txt"), b"keep").unwrap();
+    assert!(workspace.write_stream("notes.txt", &mut |w| w.write_all(b"x")).is_err());
+    assert_eq!(std::fs::read(inside.join("notes.txt")).unwrap(), b"keep");
+}
+
 /// A directory at the target is refused before anything is opened, even under an image name.
 #[test]
 fn write_refuses_a_directory_target_before_opening_it() {

From be3b2918c34fc83363b5143dbbe1e16441479824 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 12:16:23 +0100
Subject: [PATCH 089/109] raster: checksum stage-file appends and fail a read
 pass over changed bytes

Like the tile scratch file, each append records a CRC-32; a save copying it (whole or
in consecutive parts) fails on the last part if the scratch disk returned different
bytes, so the document is never replaced with them.
---
 crates/raster/src/stage_file.rs | 74 +++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 4 deletions(-)

diff --git a/crates/raster/src/stage_file.rs b/crates/raster/src/stage_file.rs
index e371fbe6be..aff858c279 100644
--- a/crates/raster/src/stage_file.rs
+++ b/crates/raster/src/stage_file.rs
@@ -6,7 +6,13 @@
 //! disk instead: an append-only file made like the tile scratch file (private, unlinked on Unix,
 //! delete-on-close on Windows), so nothing is left behind at any exit, and the space returns as
 //! soon as the save drops it.
+//!
+//! Like the tile scratch file, every append carries a CRC-32: a read pass that covers an append
+//! from its start to its end (whole, or in consecutive parts, as a save copies it) fails on its
+//! last part if the disk handed back different bytes, so the save errors before it replaces
+//! anything instead of writing them into the document.
 
+use std::collections::BTreeMap;
 use std::fs::File;
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, PoisonError};
@@ -20,6 +26,16 @@ pub struct StageFile {
     linked: bool,
     /// Bytes reserved so far; appends take their offset from it.
     end: Mutex<u64>,
+    /// Each append by its offset, with its checksum and the read pass under way.
+    extents: Mutex<BTreeMap<u64, Extent>>,
+}
+
+struct Extent {
+    len: u64,
+    crc32: u32,
+    /// Where the current read pass continues (`None` once it skipped or jumped: not checked).
+    next: Option<u64>,
+    hasher: crc32fast::Hasher,
 }
 
 impl std::fmt::Debug for StageFile {
@@ -32,7 +48,7 @@ impl StageFile {
     /// A new, empty stage file in `dir`.
     pub fn create(dir: &Path) -> std::io::Result<Self> {
         let (file, path, linked) = open_private(dir)?;
-        Ok(Self { file, path, linked, end: Mutex::new(0) })
+        Ok(Self { file, path, linked, end: Mutex::new(0), extents: Mutex::default() })
     }
 
     /// A stage file in the configured scratch directory, when spilling is on (`None` otherwise,
@@ -53,15 +69,42 @@ impl StageFile {
             offset
         };
         write_all_at(&self.file, data, offset)?;
+        let extent = Extent { len: data.len() as u64, crc32: crc32fast::hash(data), next: Some(offset), hasher: crc32fast::Hasher::new() };
+        self.extents.lock().unwrap_or_else(PoisonError::into_inner).insert(offset, extent);
         Ok(offset)
     }
 
-    /// Fills `buf` from `offset`, which must lie within what was appended.
+    /// Fills `buf` from `offset`, which must lie within what was appended. A read that ends a
+    /// pass over one append from its start fails with `InvalidData` if the append's bytes changed.
     pub fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> std::io::Result<()> {
-        if offset.checked_add(buf.len() as u64).is_none_or(|end| end > self.len()) {
+        let Some(end) = offset.checked_add(buf.len() as u64).filter(|&end| end <= self.len()) else {
             return Err(std::io::ErrorKind::UnexpectedEof.into());
+        };
+        read_exact_at(&self.file, buf, offset)?;
+        let mut extents = self.extents.lock().unwrap_or_else(PoisonError::into_inner);
+        let Some((&start, extent)) = extents.range_mut(..=offset).next_back() else { return Ok(()) };
+        let extent_end = start + extent.len;
+        if end > extent_end {
+            return Ok(()); // spans appends (no save reads this way): not checked
         }
-        read_exact_at(&self.file, buf, offset)
+        if offset == start {
+            extent.hasher = crc32fast::Hasher::new();
+            extent.next = Some(start);
+        }
+        if extent.next != Some(offset) {
+            extent.next = None;
+            return Ok(());
+        }
+        extent.hasher.update(buf);
+        extent.next = Some(end);
+        if end == extent_end {
+            let crc32 = std::mem::take(&mut extent.hasher).finalize();
+            extent.next = None;
+            if crc32 != extent.crc32 {
+                return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "staged save data changed on the scratch disk (checksum mismatch)"));
+            }
+        }
+        Ok(())
     }
 
     /// Bytes appended (reserved) so far.
@@ -109,4 +152,27 @@ mod tests {
         assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 0);
         let _ = std::fs::remove_dir(&dir);
     }
+
+    /// Bytes that change on the disk fail the pass that copies them, whole or in parts.
+    #[test]
+    fn a_changed_append_fails_its_read_pass() {
+        let dir = std::env::temp_dir().join(format!("pc-stage-crc-{}", std::process::id()));
+        let stage = StageFile::create(&dir).unwrap();
+        let first = stage.append(&[1; 100]).unwrap();
+        let second = stage.append(&[2; 100]).unwrap();
+        let pass = |at: u64, part: usize| -> std::io::Result<()> {
+            let mut buf = vec![0; part];
+            (0..100 / part as u64).try_for_each(|i| stage.read_exact_at(&mut buf, at + i * part as u64))
+        };
+        pass(first, 10).unwrap();
+        pass(second, 100).unwrap();
+        write_all_at(&stage.file, &[9], second + 57).unwrap();
+        pass(first, 25).unwrap();
+        assert_eq!(pass(second, 10).unwrap_err().kind(), std::io::ErrorKind::InvalidData, "in parts");
+        assert_eq!(pass(second, 100).unwrap_err().kind(), std::io::ErrorKind::InvalidData, "whole");
+        let mut part = [0; 10];
+        stage.read_exact_at(&mut part, second + 50).unwrap(); // a read that starts mid-append is not a pass
+        drop(stage);
+        let _ = std::fs::remove_dir(&dir);
+    }
 }

From 0a528eea1934cebb5dc7539d86286687ba591042 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 12:16:23 +0100
Subject: [PATCH 090/109] automation: remove the temp file on every exit but a
 rename, a panicking writer included

A drop guard armed only once this call created the temp file replaces the error-path
remove_file, so a writer panic no longer leaves a temp file and a create_new collision
never removes a file this call did not make.
---
 crates/automation/src/workspace.rs       | 23 +++++++++++++++++++++--
 crates/automation/src/workspace/tests.rs | 16 ++++++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/crates/automation/src/workspace.rs b/crates/automation/src/workspace.rs
index d288f42f61..3e068258fe 100644
--- a/crates/automation/src/workspace.rs
+++ b/crates/automation/src/workspace.rs
@@ -117,7 +117,11 @@ impl AuthorizedWorkspace {
         let tmp = parent.join(photocraft_format::atomic::temp_name(&leaf));
         let mut options = OpenOptions::new();
         options.write(true).create_new(true);
-        let written = root.dir.open_with(&tmp, &options).and_then(|file| {
+        let opened = root.dir.open_with(&tmp, &options);
+        // Removes the temporary file on every way out but a rename, a panicking writer included
+        // (unwinding closes the handle inside the closure first), and only one this call made.
+        let mut cleanup = TempRemoval { dir: &root.dir, path: &tmp, armed: opened.is_ok() };
+        let written = opened.and_then(|file| {
             let mut file = file.into_std();
             write(&mut file)?;
             #[cfg(unix)]
@@ -137,9 +141,9 @@ impl AuthorizedWorkspace {
         });
         let renamed = written.and_then(|()| photocraft_format::atomic::retry_rename(RenameRetry::platform(), || root.dir.rename(&tmp, &root.dir, &relative)));
         if let Err(e) = renamed {
-            let _ = root.dir.remove_file(&tmp);
             return Err(file_error("write", path, e));
         }
+        cleanup.armed = false;
         // Flush the directory entry (Unix); best effort, the new bytes are already in place.
         #[cfg(unix)]
         {
@@ -152,6 +156,21 @@ impl AuthorizedWorkspace {
     }
 }
 
+/// Removes a temporary file on drop unless `armed` was cleared after its rename.
+struct TempRemoval<'a> {
+    dir: &'a Dir,
+    path: &'a Path,
+    armed: bool,
+}
+
+impl Drop for TempRemoval<'_> {
+    fn drop(&mut self) {
+        if self.armed {
+            let _ = self.dir.remove_file(self.path);
+        }
+    }
+}
+
 /// Whether `name`'s extension is one of the formats PhotoCraft saves or exports.
 fn written_kind(name: &str) -> bool {
     let Some((_, ext)) = name.rsplit_once('.') else { return false };
diff --git a/crates/automation/src/workspace/tests.rs b/crates/automation/src/workspace/tests.rs
index d44f984ece..5ea4a5b3fe 100644
--- a/crates/automation/src/workspace/tests.rs
+++ b/crates/automation/src/workspace/tests.rs
@@ -152,6 +152,22 @@ fn write_stream_seeks_back_and_keeps_the_original_on_failure() {
     assert_eq!(std::fs::read(inside.join("notes.txt")).unwrap(), b"keep");
 }
 
+/// A writer that panics leaves the original and no temporary file behind.
+#[test]
+fn write_stream_cleans_up_after_a_panicking_writer() {
+    let (inside, _, workspace) = roots("stream-panic");
+    workspace.write("big.psb", b"original").unwrap();
+    let unwound = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        let _ = workspace.write_stream("big.psb", &mut |w| {
+            w.write_all(b"partial")?;
+            panic!("encoder bug")
+        });
+    }));
+    assert!(unwound.is_err());
+    assert_eq!(std::fs::read(inside.join("big.psb")).unwrap(), b"original");
+    assert!(temp_files(&inside).is_empty());
+}
+
 /// A directory at the target is refused before anything is opened, even under an image name.
 #[test]
 fn write_refuses_a_directory_target_before_opening_it() {

From afa0a86341d76c13aede6a87df57d37665e6b4dc Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 13:06:09 +0100
Subject: [PATCH 091/109] psd: widen staged RLE data to PSB in short reads,
 never reading it back whole

---
 crates/psd/src/compression.rs | 15 +++++++---
 crates/psd/src/file.rs        | 52 +++++++++++++++++++++++++++++++----
 crates/psd/src/io.rs          | 39 ++++++++++++++++++++++----
 crates/psd/src/layer.rs       |  8 +++---
 4 files changed, 95 insertions(+), 19 deletions(-)

diff --git a/crates/psd/src/compression.rs b/crates/psd/src/compression.rs
index 5a49284c44..73c71bab1d 100644
--- a/crates/psd/src/compression.rs
+++ b/crates/psd/src/compression.rs
@@ -228,11 +228,18 @@ pub fn decode_planes(compression: Compression, data: &[u8], layout: &PlaneLayout
 /// Bytes a PSD RLE stream (two-byte row counts) of `rows` rows grows by when written as PSB
 /// (four-byte row counts); an error when `data` is too short to hold the count table.
 pub(crate) fn rle_widening(data: &[u8], rows: usize) -> Result<u64> {
-    let table = rows.checked_mul(2).ok_or(PsdError::LimitExceeded("row count overflow"))?;
-    if data.len() < table {
-        return Err(PsdError::UnexpectedEof { offset: data.len(), needed: table - data.len() });
+    rle_widening_len(data.len() as u64, rows)
+}
+
+/// [`rle_widening`] from the stream's length alone, so data still in its source (or staged on
+/// the scratch disk) is not read to measure it.
+pub(crate) fn rle_widening_len(len: u64, rows: usize) -> Result<u64> {
+    let table = rows.checked_mul(2).ok_or(PsdError::LimitExceeded("row count overflow"))? as u64;
+    if len < table {
+        let offset = usize::try_from(len).unwrap_or(usize::MAX);
+        return Err(PsdError::UnexpectedEof { offset, needed: usize::try_from(table - len).unwrap_or(usize::MAX) });
     }
-    Ok(table as u64)
+    Ok(table)
 }
 
 /// Encodes planar data (excluding the 2-byte compression field).
diff --git a/crates/psd/src/file.rs b/crates/psd/src/file.rs
index babcef4f58..910d19563a 100644
--- a/crates/psd/src/file.rs
+++ b/crates/psd/src/file.rs
@@ -2,7 +2,7 @@
 
 use std::io::{Seek, Write};
 
-use crate::compression::{Compression, MAX_DECODED_BYTES, decode_planes, rle_widening, validate_planes};
+use crate::compression::{Compression, MAX_DECODED_BYTES, decode_planes, rle_widening_len, validate_planes};
 use crate::error::{PsdError, Result};
 use crate::header::{ColorMode, Header, Version};
 use crate::image_data::ImageData;
@@ -384,7 +384,7 @@ impl PsdFile {
         })?;
         match self.merged_widened_rows(widen)? {
             0 => out.put_encoded(&self.image_data.data, self.image_data.stored.as_ref()),
-            rows => out.put_widened_rle(&self.image_data.encoded()?, rows),
+            rows => out.put_widened_encoded(&self.image_data.data, self.image_data.stored.as_ref(), rows),
         }
     }
 
@@ -414,13 +414,13 @@ impl PsdFile {
             for c in &layer.channels {
                 match layer.widened_rows(c, true)? {
                     0 => {}
-                    rows => n = n.saturating_add(rle_widening(&c.encoded()?, rows)?),
+                    rows => n = n.saturating_add(rle_widening_len(c.encoded_len(), rows)?),
                 }
             }
         }
         match self.merged_widened_rows(true)? {
             0 => Ok(n),
-            rows => Ok(n.saturating_add(rle_widening(&self.image_data.encoded()?, rows)?)),
+            rows => Ok(n.saturating_add(rle_widening_len(self.image_data.encoded_len(), rows)?)),
         }
     }
 
@@ -463,7 +463,7 @@ impl PsdFile {
         }
         let merged = match self.merged_widened_rows(widen)? {
             0 => 0,
-            rows => rle_widening(&self.image_data.encoded()?, rows)?,
+            rows => rle_widening_len(self.image_data.encoded_len(), rows)?,
         };
         Ok(n.saturating_add(2).saturating_add(self.image_data.encoded_len()).saturating_add(merged))
     }
@@ -747,6 +747,48 @@ mod write_tests {
         assert!(*source.1.lock().unwrap() <= 7, "read {} bytes at once", source.1.lock().unwrap());
     }
 
+    /// #5333: RLE data still in its source widens to PSB in short reads too, the count table and
+    /// then the packed rows, one consecutive pass, never the whole merged image or channel at once.
+    #[test]
+    fn source_backed_rle_widens_in_short_reads() {
+        struct Reads(Vec<u8>, std::sync::Mutex<(usize, Vec<(u64, usize)>)>);
+        impl crate::source::ReadAt for Reads {
+            fn len(&self) -> u64 {
+                self.0.len() as u64
+            }
+            fn read_at(&self, offset: u64, buf: &mut [u8]) -> Result<()> {
+                let mut seen = self.1.lock().unwrap();
+                seen.0 = seen.0.max(buf.len());
+                seen.1.push((offset, buf.len()));
+                self.0.as_slice().read_at(offset, buf)
+            }
+        }
+        let file = testgen::small(Version::Psd, Compression::Rle);
+        assert_eq!(file.image_data.compression, Compression::Rle);
+        let bytes = file.to_bytes().unwrap();
+        let mut promoted = file.clone();
+        promoted.promote_to_psb().unwrap();
+        let want = promoted.to_bytes().unwrap();
+        let source = std::sync::Arc::new(Reads(bytes, std::sync::Mutex::new((0, Vec::new()))));
+        let mut lazy = PsdFile::from_source(crate::Source::from_arc(source.clone())).unwrap();
+        assert!(lazy.image_data.stored.is_some(), "the merged image stays in the source");
+        lazy.promote_to_psb().unwrap();
+        *source.1.lock().unwrap() = (0, Vec::new());
+        let mut w = std::io::Cursor::new(Vec::new());
+        lazy.write_to(&mut w).unwrap();
+        assert!(w.into_inner() == want);
+        let seen = source.1.lock().unwrap();
+        assert!(seen.0 <= 7, "read {} bytes at once", seen.0);
+        let merged = lazy.image_data.stored.as_ref().unwrap();
+        let reads: Vec<_> = seen.1.iter().filter(|(at, _)| (merged.offset..merged.offset + merged.len).contains(at)).collect();
+        let mut next = merged.offset;
+        for &&(at, n) in &reads {
+            assert_eq!(at, next, "the merged image is read in one consecutive pass");
+            next += n as u64;
+        }
+        assert_eq!(next, merged.offset + merged.len);
+    }
+
     /// #6607: pixel data goes to the stream as it is, never through a staging copy, so a save
     /// holds the model and a short buffer, not a second copy of the file.
     #[test]
diff --git a/crates/psd/src/io.rs b/crates/psd/src/io.rs
index bf4468711a..8537b74649 100644
--- a/crates/psd/src/io.rs
+++ b/crates/psd/src/io.rs
@@ -275,16 +275,43 @@ impl<'w, W: Write + Seek + ?Sized> Sink<'w, W> {
         let table_len = usize::try_from(crate::compression::rle_widening(data, rows)?).map_err(|_| PsdError::LimitExceeded("row count overflow"))?;
         let (table, packed) = data.split_at_checked(table_len).ok_or_else(|| PsdError::invalid("RLE row-count table out of range"))?;
         for part in table.chunks(STAGE / 2) {
-            self.small(|o| {
-                for count in part.as_chunks::<2>().0 {
-                    o.extend_from_slice(&[0, 0, count[0], count[1]]);
-                }
-                Ok(())
-            })?;
+            self.widen_counts(part)?;
         }
         self.put(packed)
     }
 
+    /// [`Self::put_widened_rle`] for data held in memory (`data`) or, when `stored`, still in its
+    /// source: the count table and then the packed rows are read in [`COPY_CHUNK`]-sized parts
+    /// (#5333), so a staged merged image or channel is never read back whole to widen it.
+    pub(crate) fn put_widened_encoded(&mut self, data: &[u8], stored: Option<&crate::source::Stored>, rows: usize) -> std::io::Result<()> {
+        let Some(s) = stored else { return self.put_widened_rle(data, rows) };
+        let table_len = crate::compression::rle_widening_len(s.len, rows)?;
+        // Whole counts per part; the parts follow each other, so a staged range is read in one pass.
+        let table_part = (COPY_CHUNK / 2).max(1) * 2;
+        let mut at = 0u64;
+        while at < s.len {
+            let n = if at < table_len { (table_len - at).min(table_part) } else { (s.len - at).min(COPY_CHUNK) };
+            let part = s.read_part(at, n)?;
+            if at < table_len {
+                self.widen_counts(&part)?
+            } else {
+                self.put(&part)?
+            }
+            at += n;
+        }
+        Ok(())
+    }
+
+    /// Two-byte RLE row counts as four-byte ones (`00 00` and the count), staged.
+    fn widen_counts(&mut self, counts: &[u8]) -> std::io::Result<()> {
+        self.small(|o| {
+            for count in counts.as_chunks::<2>().0 {
+                o.extend_from_slice(&[0, 0, count[0], count[1]]);
+            }
+            Ok(())
+        })
+    }
+
     /// Appends encoded bytes held in memory (`data`) or, when `stored`, still in their source:
     /// those are copied through in [`COPY_CHUNK`] pieces, so a channel or merged image kept on
     /// disk (an imported file's, or one an exporter spilled to scratch) is never read whole.
diff --git a/crates/psd/src/layer.rs b/crates/psd/src/layer.rs
index 3b492e6a04..90f6550863 100644
--- a/crates/psd/src/layer.rs
+++ b/crates/psd/src/layer.rs
@@ -3,7 +3,7 @@
 use std::borrow::Cow;
 
 use crate::blend::BlendMode;
-use crate::compression::{Compression, PlaneLayout, decode_planes, encode_planes, rle_widening};
+use crate::compression::{Compression, PlaneLayout, decode_planes, encode_planes, rle_widening_len};
 use crate::error::{PsdError, Result};
 use crate::header::{MAX_DIMENSION, Version};
 use crate::io::{Reader, Sink, WriteExt, append_with, decode_legacy_name, read_pascal, write_pascal};
@@ -692,7 +692,7 @@ impl LayerRecord {
         for c in &self.channels {
             out.put_i16(c.id);
             let rows = self.widened_rows(c, widen)?;
-            let grown = if rows == 0 { 0 } else { rle_widening(&c.encoded()?, rows)? };
+            let grown = if rows == 0 { 0 } else { rle_widening_len(c.encoded_len(), rows)? };
             out.put_len(c.stored_len().saturating_add(grown), version.is_psb())?;
         }
         out.put(b"8BIM");
@@ -783,7 +783,7 @@ impl LayerInfo {
         for l in &self.layers {
             for c in l.channels.iter().filter(|c| c.compression.is_some()) {
                 let rows = l.widened_rows(c, widen)?;
-                let grown = if rows == 0 { 0 } else { rle_widening(&c.encoded()?, rows)? };
+                let grown = if rows == 0 { 0 } else { rle_widening_len(c.encoded_len(), rows)? };
                 n = n.saturating_add(2).saturating_add(c.encoded_len()).saturating_add(grown);
             }
         }
@@ -860,7 +860,7 @@ impl LayerInfo {
                     })?;
                     match l.widened_rows(c, widen)? {
                         0 => out.put_encoded(&c.data, c.stored.as_ref())?,
-                        rows => out.put_widened_rle(&c.encoded()?, rows)?,
+                        rows => out.put_widened_encoded(&c.data, c.stored.as_ref(), rows)?,
                     }
                 }
             }

From 52eed152817771aa0392fa8e0ef2c6d74dcdf727 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 13:21:06 +0100
Subject: [PATCH 092/109] io: save layers past the gather size band by band,
 with their pixels, staged as they are encoded

---
 crates/io/src/psd_export.rs        |  13 ++-
 crates/io/src/psd_export/banded.rs | 134 +++++++++++++++++++++++++++++
 crates/io/src/psd_export/stage.rs  | 120 ++++++++++++++++++++++++++
 crates/io/src/psd_export/tests.rs  | 127 +++++++++++++++++++++++++++
 4 files changed, 386 insertions(+), 8 deletions(-)
 create mode 100644 crates/io/src/psd_export/banded.rs

diff --git a/crates/io/src/psd_export.rs b/crates/io/src/psd_export.rs
index 6f87aa7588..a98cb347b1 100644
--- a/crates/io/src/psd_export.rs
+++ b/crates/io/src/psd_export.rs
@@ -15,6 +15,7 @@ use crate::blocks;
 use crate::pixels::{deinterleave, encode_be, psd_depth};
 use crate::psd_import::REGENERATED;
 
+mod banded;
 mod document;
 mod estimate;
 mod merged;
@@ -43,10 +44,6 @@ const PSD_MAX_FILE_SIZE: u64 = 2 * 1024 * 1024 * 1024;
 /// Room kept under [`PSD_MAX_FILE_SIZE`] for what the save adds after the conversion (the image
 /// preview resource, a few KB).
 const PSD_SAVE_HEADROOM: u64 = 1024 * 1024;
-/// Most bytes of one layer's interleaved samples the exporter gathers. The interleaved bytes and
-/// the channel planes made from them (or the band parts and the joined buffer) are alive together,
-/// so the peak is about twice this; it is also what fits in a file of at most [`PSD_MAX_FILE_SIZE`].
-const MAX_LAYER_GATHER_BYTES: u64 = if cfg!(target_pointer_width = "64") { 1 << 30 } else { 256 << 20 };
 
 /// Options for [`document_to_psd_with`].
 #[derive(Debug, Clone)]
@@ -221,11 +218,11 @@ impl Ex {
             return (PsdRect::default(), self.empty_channels(), warnings);
         }
         // A layer record is one dense rectangle, so a few pixels far apart make a box of mostly
-        // nothing, gathered and then copied again. Past the cap the layer is saved empty, said so.
+        // nothing, gathered and then copied again. Past `banded_from` the layer is gathered and
+        // encoded a band of rows at a time instead (#5333).
         let dense = u64::from(r.width()).saturating_mul(u64::from(r.height())).saturating_mul(s.format().bytes_per_pixel() as u64);
-        if dense > MAX_LAYER_GATHER_BYTES {
-            warnings.push(format!("layer \"{name}\" spans {}×{} px, too large to write: saved without its pixels", r.width(), r.height()));
-            return (PsdRect::default(), self.empty_channels(), warnings);
+        if dense > banded::banded_from() {
+            return (to_psd_rect(r), self.banded_channels(&s, r), warnings);
         }
         // The interleaved gather is the sequential pass for full-canvas layers, so it runs
         // in row bands on all cores and the band results concatenate in order.
diff --git a/crates/io/src/psd_export/banded.rs b/crates/io/src/psd_export/banded.rs
new file mode 100644
index 0000000000..f2fc0a7751
--- /dev/null
+++ b/crates/io/src/psd_export/banded.rs
@@ -0,0 +1,134 @@
+//! Layers too large to gather at once, saved band by band (#5333).
+//!
+//! A layer record is one dense rectangle, gathered interleaved and split into channel planes,
+//! so a layer's save held about twice its dense size; past [`BANDED_FROM`] that was refused and the
+//! layer saved without its pixels. Now such a layer is gathered, split and encoded a band of
+//! rows at a time. RLE rows pack independently (the row-count table is kept and written ahead of
+//! the packed rows) and raw rows join, so those channels are the bytes the whole-layer encoder
+//! writes. ZIP with prediction (32-bit) predicts per row and feeds one zlib stream: the same
+//! pixels, but not always the same bytes, as zlib packs input it is given in parts differently.
+//! With a stage each band's parts go to the scratch disk as they are made (see [`Parts`]).
+
+use std::io::Write as _;
+
+use photocraft_psd::compression::{PlaneLayout, encode_planes, predict};
+use photocraft_psd::{ChannelData, Compression, PsdError};
+use photocraft_raster::Surface;
+
+use super::Ex;
+use super::stage::Parts;
+use crate::pixels::{deinterleave, psd_depth};
+
+/// Dense bytes of one layer (as gathered) from which it is saved band by band. Below it a layer
+/// is gathered whole, which is faster: the peak is about twice this.
+pub(super) const BANDED_FROM: u64 = if cfg!(target_pointer_width = "64") { 1 << 30 } else { 256 << 20 };
+/// Interleaved bytes gathered per band. A band's planes and encoded parts are alive with it, so a
+/// banded layer's save holds about three times this.
+const BAND_BYTES: usize = 64 << 20;
+
+#[cfg(test)]
+thread_local! {
+    /// `(BANDED_FROM, BAND_BYTES)` for this thread's exports, so tests band small layers.
+    pub(crate) static BANDS_FOR_TESTS: std::cell::Cell<Option<(u64, usize)>> = const { std::cell::Cell::new(None) };
+}
+
+pub(super) fn banded_from() -> u64 {
+    #[cfg(test)]
+    if let Some((from, _)) = BANDS_FOR_TESTS.get() {
+        return from;
+    }
+    BANDED_FROM
+}
+
+fn band_bytes() -> usize {
+    #[cfg(test)]
+    if let Some((_, bytes)) = BANDS_FOR_TESTS.get() {
+        return bytes;
+    }
+    BAND_BYTES
+}
+
+/// One channel's encoding state across bands.
+struct Channel {
+    id: i16,
+    table: Vec<u8>,
+    zip: Option<flate2::write::ZlibEncoder<Vec<u8>>>,
+    parts: Parts,
+}
+
+impl Ex {
+    /// The channels of `s` over `r` (non-empty), alpha first, encoded band by band.
+    pub(super) fn banded_channels(&self, s: &Surface, r: photocraft_geom::Rect) -> Vec<ChannelData> {
+        // RLE fails only on a row too long for its count (not within PSD/PSB limits); then the
+        // layer is written raw, as a channel encoded whole falls back to.
+        self.banded_pass(s, r, self.compression()).or_else(|_| self.banded_pass(s, r, Compression::Raw)).unwrap_or_else(|_| self.empty_channels())
+    }
+
+    fn banded_pass(&self, s: &Surface, r: photocraft_geom::Rect, compression: Compression) -> photocraft_psd::Result<Vec<ChannelData>> {
+        let (w, h) = (r.width() as usize, r.height() as usize);
+        let bpp = s.format().bytes_per_pixel();
+        let band_rows = (band_bytes() / (w * bpp).max(1)).max(1);
+        let depth = psd_depth(self.fmt.sample);
+        let count = if self.version.is_psb() { 4 } else { 2 };
+        let head = if compression == Compression::Rle { h.checked_mul(count).ok_or(PsdError::LimitExceeded("row count overflow"))? } else { 0 };
+        let mut channels: Vec<Channel> = (0..=self.cc)
+            .map(|k| Channel {
+                id: k as i16 - 1,
+                table: Vec::with_capacity(head),
+                zip: (compression == Compression::ZipPrediction).then(|| flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::default())),
+                parts: Parts::new(self.stage.clone(), head),
+            })
+            .collect();
+        let mut invert = vec![self.cmyk; self.cc];
+        invert.push(false);
+        for y in (0..h).step_by(band_rows) {
+            let rows = band_rows.min(h - y);
+            let top = r.y0 + y as i32;
+            let pieces = crate::pixels::par_map(crate::pixels::bands(rows), |b| {
+                s.to_interleaved(photocraft_geom::Rect::new(r.x0, top + b.start as i32, r.x1, top + b.end as i32))
+            });
+            let mut bytes = Vec::with_capacity(w * rows * bpp);
+            for piece in pieces {
+                bytes.extend_from_slice(&piece);
+            }
+            if self.fmt.mode == photocraft_color::ColorMode::Lab && self.fmt.sample == photocraft_color::SampleType::U16 {
+                crate::pixels::lab16_chroma(&mut bytes, self.cc + 1, false);
+            }
+            let mut planes: Vec<Option<Vec<u8>>> = deinterleave(&bytes, self.cc + 1, self.fmt.sample, &invert).into_iter().map(Some).collect();
+            drop(bytes);
+            let layout = PlaneLayout { planes: 1, width: w, height: rows, depth, version: self.version };
+            // Alpha (planes[cc]) is channel 0, then the colour channels; each on its own thread.
+            let work: Vec<(&mut Channel, Vec<u8>)> =
+                channels.iter_mut().enumerate().map(|(k, c)| (c, planes[if k == 0 { self.cc } else { k - 1 }].take().unwrap_or_default())).collect();
+            let done = crate::pixels::par_map(work, |(c, mut plane)| -> photocraft_psd::Result<()> {
+                match compression {
+                    Compression::Rle => {
+                        let mut packed = encode_planes(Compression::Rle, &plane, &layout)?;
+                        let rest = packed.split_off(rows * count);
+                        c.table.extend_from_slice(&packed);
+                        c.parts.push(rest);
+                    }
+                    Compression::ZipPrediction => {
+                        predict(&mut plane, &layout)?;
+                        let zip = c.zip.as_mut().ok_or_else(|| PsdError::Invalid("banded ZIP channel without its stream".into()))?;
+                        zip.write_all(&plane).map_err(|e| PsdError::Invalid(format!("zlib: {e}")))?;
+                        let out = std::mem::take(zip.get_mut());
+                        c.parts.push(out);
+                    }
+                    _ => c.parts.push(plane),
+                }
+                Ok(())
+            });
+            done.into_iter().collect::<photocraft_psd::Result<()>>()?;
+        }
+        channels
+            .into_iter()
+            .map(|mut c| {
+                if let Some(zip) = c.zip.take() {
+                    c.parts.push(zip.finish().map_err(|e| PsdError::Invalid(format!("zlib: {e}")))?);
+                }
+                c.parts.finish(c.id, compression, &c.table)
+            })
+            .collect()
+    }
+}
diff --git a/crates/io/src/psd_export/stage.rs b/crates/io/src/psd_export/stage.rs
index 3e04d53247..869208e319 100644
--- a/crates/io/src/psd_export/stage.rs
+++ b/crates/io/src/psd_export/stage.rs
@@ -95,9 +95,129 @@ impl Stage {
         image
     }
 
+    /// Appends one part of a channel written band by band; `None` when the write fails.
+    fn append(&self, data: &[u8]) -> Option<u64> {
+        self.file.0.append(data).ok()
+    }
+
     /// Bytes on the scratch disk.
     #[cfg(test)]
     pub(crate) fn len(&self) -> u64 {
         self.file.0.len()
     }
 }
+
+/// One channel of a layer encoded band by band (#5333): its head (an RLE row-count table, filled
+/// in when the last band is encoded) and the bands' encoded parts in order. With a stage every
+/// part goes to the scratch disk as it is made, so a layer of any size is saved holding about one
+/// band; without one the parts are joined in memory, as a channel encoded whole would be.
+pub(crate) struct Parts {
+    stage: Option<Arc<Stage>>,
+    head_len: usize,
+    /// Without a stage: the head's room and the parts so far.
+    joined: Vec<u8>,
+    /// With a stage: the parts, staged or (when a write failed) kept.
+    parts: Vec<Part>,
+    len: u64,
+}
+
+enum Part {
+    Kept(Vec<u8>),
+    Staged { offset: u64, len: u64 },
+}
+
+impl Part {
+    fn len(&self) -> u64 {
+        match self {
+            Part::Kept(v) => v.len() as u64,
+            Part::Staged { len, .. } => *len,
+        }
+    }
+}
+
+impl Parts {
+    pub(crate) fn new(stage: Option<Arc<Stage>>, head_len: usize) -> Self {
+        let joined = if stage.is_none() { vec![0; head_len] } else { Vec::new() };
+        Parts { stage, head_len, joined, parts: Vec::new(), len: head_len as u64 }
+    }
+
+    /// Adds the next encoded part.
+    pub(crate) fn push(&mut self, data: Vec<u8>) {
+        if data.is_empty() {
+            return;
+        }
+        self.len += data.len() as u64;
+        match &self.stage {
+            None => self.joined.extend_from_slice(&data),
+            Some(stage) => self.parts.push(match stage.append(&data) {
+                Some(offset) => Part::Staged { offset, len: data.len() as u64 },
+                None => Part::Kept(data),
+            }),
+        }
+    }
+
+    /// The channel: `head` (of the length given to [`Parts::new`]) and then the parts.
+    pub(crate) fn finish(mut self, id: i16, compression: photocraft_psd::Compression, head: &[u8]) -> photocraft_psd::Result<ChannelData> {
+        if head.len() != self.head_len {
+            return Err(PsdError::Invalid("banded channel head has the wrong length".into()));
+        }
+        let Some(stage) = self.stage else {
+            self.joined[..head.len()].copy_from_slice(head);
+            self.joined.shrink_to_fit();
+            return Ok(ChannelData::new(id, Some(compression), self.joined));
+        };
+        let mut parts = Vec::with_capacity(self.parts.len() + 1);
+        if !head.is_empty() {
+            parts.push(Part::Kept(head.to_vec()));
+        }
+        parts.append(&mut self.parts);
+        let mut starts = Vec::with_capacity(parts.len());
+        let mut at = 0;
+        for p in &parts {
+            starts.push(at);
+            at += p.len();
+        }
+        let joined = Joined { file: stage.file.clone(), parts, starts, len: self.len };
+        let stored = Stored { source: Source::from_arc(Arc::new(joined)), offset: 0, len: self.len };
+        Ok(ChannelData { id, compression: Some(compression), data: Vec::new(), stored: Some(stored) })
+    }
+}
+
+/// A banded channel's bytes, in memory and in its staged parts. A read is split at the parts, so
+/// the writer's consecutive pass reads each staged append from its start to its end, and the stage
+/// file checks it.
+struct Joined {
+    file: Arc<Backing>,
+    parts: Vec<Part>,
+    starts: Vec<u64>,
+    len: u64,
+}
+
+impl ReadAt for Joined {
+    fn len(&self) -> u64 {
+        self.len
+    }
+
+    fn read_at(&self, offset: u64, buf: &mut [u8]) -> photocraft_psd::Result<()> {
+        if offset.checked_add(buf.len() as u64).is_none_or(|end| end > self.len) {
+            return Err(PsdError::Read(format!("staged export data, {} bytes at offset {offset} past its {} bytes", buf.len(), self.len)));
+        }
+        let mut pos = offset;
+        let mut buf = buf;
+        let mut i = self.starts.partition_point(|&s| s <= pos).saturating_sub(1);
+        while !buf.is_empty() {
+            let (part, start) = (&self.parts[i], self.starts[i]);
+            let within = pos - start;
+            let n = usize::try_from((part.len() - within).min(buf.len() as u64)).unwrap_or(buf.len());
+            let (now, rest) = std::mem::take(&mut buf).split_at_mut(n);
+            match part {
+                Part::Kept(v) => now.copy_from_slice(&v[within as usize..within as usize + n]),
+                Part::Staged { offset, .. } => self.file.read_at(offset + within, now)?,
+            }
+            buf = rest;
+            pos += n as u64;
+            i += 1;
+        }
+        Ok(())
+    }
+}
diff --git a/crates/io/src/psd_export/tests.rs b/crates/io/src/psd_export/tests.rs
index 4fd78e8c73..c1d47c4777 100644
--- a/crates/io/src/psd_export/tests.rs
+++ b/crates/io/src/psd_export/tests.rs
@@ -672,3 +672,130 @@ fn staging_keeps_short_or_unwritable_data_in_memory() {
     assert!(stage::Stage::for_document(10, None).is_none(), "not asked for");
     let _ = std::fs::remove_dir(&dir);
 }
+
+/// The first layer's channels, decoded.
+fn decoded_channels(file: &PsdFile) -> Vec<Vec<u8>> {
+    let layer = &file.layers()[0];
+    let (w, h) = (layer.rect.width() as usize, layer.rect.height() as usize);
+    layer.channels.iter().map(|c| c.decode(w, h, file.header.depth, file.header.version).unwrap()).collect()
+}
+
+/// A noisy, translucent layer inset from the canvas: `w`×`h` px in `mode`/`depth`.
+fn banding_document(mode: ColorMode, depth: SampleType, w: u32, h: u32) -> Document {
+    let mut doc = Document::new("banded", photocraft_geom::Size::new(w, h), mode, depth);
+    let mut layer = Layer::raster("Layer 1", doc.pixel_format());
+    let rect = photocraft_geom::Rect::new(5, 3, w as i32 - 7, h as i32 - 2);
+    let surface = layer.surface_mut().unwrap();
+    let ch = surface.channels();
+    let mut state = 0x2545_f491_u32;
+    let n = rect.width() as usize * rect.height() as usize * ch;
+    let data: Vec<f32> = (0..n)
+        .map(|i| {
+            state ^= state << 13;
+            state ^= state >> 17;
+            state ^= state << 5;
+            // Runs as well as noise, so RLE packs both kinds of row.
+            let v = if (i / (ch * 40)).is_multiple_of(3) { 0.5 } else { (state >> 20) as f32 / 4095.0 };
+            if i % ch == ch - 1 { v.max(0.25) } else { v }
+        })
+        .collect();
+    surface.write_region(rect, &data);
+    doc.layers.push(layer);
+    doc
+}
+
+/// Exports `doc` with layers past `banded` bytes saved in bands of `rows` rows.
+fn export_banded(doc: &Document, options: &PsdExportOptions, banded: Option<usize>) -> (PsdFile, Vec<String>) {
+    let row_bytes = doc.size.width as usize * doc.pixel_format().bytes_per_pixel();
+    banded::BANDS_FOR_TESTS.set(banded.map(|rows| (0, rows * row_bytes + 3)));
+    let out = document_to_psd_sized(doc, options, 0, &Interrupt::NONE, PSD_MAX_FILE_SIZE);
+    banded::BANDS_FOR_TESTS.set(None);
+    out
+}
+
+/// #5333: a layer saved band by band (here every layer, in bands of a few rows) writes the bytes
+/// of one gathered whole (ZIP with prediction, 32-bit, the same pixels); RGB, CMYK and Lab; PSD, PSB and a PSD
+/// promoted to PSB; in memory and staged on the scratch disk (then also streamed).
+#[test]
+fn banded_layers_write_the_bytes_of_whole_ones() {
+    let dir = std::env::temp_dir().join(format!("pc-psd-banded-{}", std::process::id()));
+    let cases = [
+        (ColorMode::Rgb, SampleType::U8),
+        (ColorMode::Rgb, SampleType::U16),
+        (ColorMode::Rgb, SampleType::F32),
+        (ColorMode::Cmyk, SampleType::U8),
+        (ColorMode::Lab, SampleType::U16),
+    ];
+    for (mode, depth) in cases {
+        let doc = banding_document(mode, depth, 203, 157);
+        for force_psb in [false, true] {
+            for staged in [false, true] {
+                stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = staged.then(|| dir.clone()));
+                let options = PsdExportOptions { force_psb, stage_on_scratch_from: staged.then_some(0), ..Default::default() };
+                let (want, want_warnings) = export_banded(&doc, &options, None);
+                for rows in [1, 7, 1000] {
+                    let what = format!("{mode:?} {depth:?}, psb {force_psb}, staged {staged}, {rows} rows a band");
+                    let (file, warnings) = export_banded(&doc, &options, Some(rows));
+                    assert_eq!(warnings, want_warnings, "{what}");
+                    let layer = &file.layers()[0];
+                    assert_eq!(layer.rect, want.layers()[0].rect, "{what}");
+                    if staged {
+                        assert!(layer.channels.iter().all(|c| c.stored.is_some() && c.data.is_empty()), "{what}: banded channels are staged");
+                    }
+                    if depth == SampleType::F32 {
+                        // One zlib stream fed band by band packs differently from one fed whole
+                        // (the encoder sees a different amount of input ahead), so the ZIP
+                        // channels are compared decoded, here and as the streamed file reads back.
+                        let mut w = std::io::Cursor::new(Vec::new());
+                        file.write_to(&mut w).unwrap();
+                        let back = PsdFile::from_bytes(&w.into_inner()).unwrap();
+                        assert_eq!(decoded_channels(&back), decoded_channels(&want), "{what}: banded ZIP channels differ");
+                        assert!(back.image_data.encoded().unwrap() == want.image_data.encoded().unwrap(), "{what}");
+                        continue;
+                    }
+                    let bytes = want.to_bytes().unwrap();
+                    assert!(file.to_bytes().unwrap() == bytes, "{what}: banded bytes differ");
+                    let mut w = std::io::Cursor::new(Vec::new());
+                    file.write_to(&mut w).unwrap();
+                    assert!(w.into_inner() == bytes, "{what}: streamed banded bytes differ");
+                    if !force_psb {
+                        let (mut promoted, mut whole) = (file.clone(), want.clone());
+                        promoted.promote_to_psb().unwrap();
+                        whole.promote_to_psb().unwrap();
+                        let mut w = std::io::Cursor::new(Vec::new());
+                        promoted.write_to(&mut w).unwrap();
+                        assert!(w.into_inner() == whole.to_bytes().unwrap(), "{what}: promoted banded bytes differ");
+                    }
+                }
+            }
+        }
+    }
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+/// #5333: a layer past the gather size is saved with its pixels (it used to be saved empty, with a
+/// warning), and they come back on import.
+#[test]
+fn banded_layers_round_trip() {
+    let dir = std::env::temp_dir().join(format!("pc-psd-banded-rt-{}", std::process::id()));
+    for depth in [SampleType::U8, SampleType::U16, SampleType::F32] {
+        let doc = banding_document(ColorMode::Rgb, depth, 181, 133);
+        for staged in [false, true] {
+            stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = staged.then(|| dir.clone()));
+            let options = PsdExportOptions { stage_on_scratch_from: staged.then_some(0), ..Default::default() };
+            let (file, warnings) = export_banded(&doc, &options, Some(5));
+            assert!(warnings.is_empty(), "{warnings:?}");
+            let mut w = std::io::Cursor::new(Vec::new());
+            file.write_to(&mut w).unwrap();
+            let back = PsdFile::from_bytes(&w.into_inner()).unwrap();
+            let (read, _) = crate::psd_import::psd_to_document(&back);
+            let full = photocraft_geom::Rect::new(0, 0, doc.size.width as i32, doc.size.height as i32);
+            let want = doc.layers[0].surface().unwrap().read_region(full);
+            let got = read.layers[0].surface().unwrap().read_region(full);
+            assert!(got == want, "{depth:?}, staged {staged}: pixels differ after the round trip");
+        }
+    }
+    stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
+    let _ = std::fs::remove_dir_all(&dir);
+}

From 381d42ad416b12443462e23fc8d5ad9007c79185 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 13:58:35 +0100
Subject: [PATCH 093/109] Viewport preview: sample the last document pixel for
 partial edge cells

A partial reduced cell at the document's right or bottom edge sampled
c*k + k/2, past the document, so the provisional preview showed the
layer's default there instead of the edge pixel. Clamp the sample to the
last document pixel (document bounds, so neighbouring pages agree).

Addresses CodeRabbit review r4454088350 on #5332.
---
 crates/compose/src/viewport.rs | 53 ++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/crates/compose/src/viewport.rs b/crates/compose/src/viewport.rs
index c7a5cc3c10..fe4db1551b 100644
--- a/crates/compose/src/viewport.rs
+++ b/crates/compose/src/viewport.rs
@@ -25,56 +25,63 @@ pub fn preview_page(doc: &Document, source: Rect, factor: u32, interrupt: Interr
     if rect.width() > 1024 || rect.height() > 1024 {
         return Err("viewport page is too large".into());
     }
-    fn shrink(s: &Surface, r: Rect, k: i32, i: Interrupt<'_>) -> Result<Surface, String> {
+    // Cell `c` samples source pixel `c·k + k/2`, clamped to the last document pixel: a partial
+    // cell at the document's edge samples inside it, not the layer's default past it. (Document
+    // bounds, not this page's, so neighbouring pages agree.)
+    let bounds = doc.bounds();
+    let last = (bounds.x1 - 1, bounds.y1 - 1);
+    fn shrink(s: &Surface, r: Rect, k: i32, last: (i32, i32), i: Interrupt<'_>) -> Result<Surface, String> {
         let mut out = Surface::with_default(s.format(), &s.default_pixel());
         let bpp = s.format().bytes_per_pixel();
+        let x0 = r.x0.saturating_mul(k);
         for y in r.y0..r.y1 {
             i.check().map_err(|e| e.to_string())?;
-            let sy = y.saturating_mul(k).saturating_add(k / 2);
-            let row = s.to_interleaved(Rect::new(r.x0.saturating_mul(k), sy, r.x1.saturating_mul(k), sy.saturating_add(1)));
+            let sy = y.saturating_mul(k).saturating_add(k / 2).min(last.1);
+            let row = s.to_interleaved(Rect::new(x0, sy, r.x1.saturating_mul(k).min(last.0 + 1), sy.saturating_add(1)));
             let mut reduced = Vec::with_capacity(r.width() as usize * bpp);
-            for x in 0..r.width() as usize {
-                let offset = (x * k as usize + k as usize / 2) * bpp;
+            for x in r.x0..r.x1 {
+                let sx = x.saturating_mul(k).saturating_add(k / 2).min(last.0);
+                let offset = (sx - x0) as usize * bpp;
                 reduced.extend_from_slice(row.get(offset..offset + bpp).ok_or("invalid viewport sample")?);
             }
             out.write_interleaved(Rect::new(r.x0, y, r.x1, y + 1), &reduced);
         }
         Ok(out)
     }
-    fn layer(l: &mut photocraft_doc::Layer, r: Rect, k: i32, i: Interrupt<'_>, depth: usize) -> Result<(), String> {
+    fn layer(l: &mut photocraft_doc::Layer, r: Rect, k: i32, i: Interrupt<'_>, depth: usize, last: (i32, i32)) -> Result<(), String> {
         if depth > 256 {
             return Err("viewport layer nesting limit exceeded".into());
         }
         if let Some(m) = &mut l.mask {
-            m.surface = shrink(&m.surface, r, k, i)?;
+            m.surface = shrink(&m.surface, r, k, last, i)?;
         }
         if let Some(c) = &mut l.fill_cache {
-            c.surface = shrink(&c.surface, r, k, i)?;
+            c.surface = shrink(&c.surface, r, k, last, i)?;
         }
         use photocraft_doc::LayerContent;
         match &mut l.content {
-            LayerContent::Raster(s) => *s = shrink(s, r, k, i)?,
+            LayerContent::Raster(s) => *s = shrink(s, r, k, last, i)?,
             LayerContent::Group(g) => {
                 if let Some(a) = &mut g.artboard {
                     a.rect = Rect::new(a.rect.x0.div_euclid(k), a.rect.y0.div_euclid(k), a.rect.x1.div_euclid(k), a.rect.y1.div_euclid(k));
                 }
                 for c in &mut g.children {
-                    layer(c, r, k, i, depth + 1)?;
+                    layer(c, r, k, i, depth + 1, last)?;
                 }
             }
             LayerContent::Text(t) => {
                 if let Some(s) = &mut t.cache {
-                    *s = shrink(s, r, k, i)?;
+                    *s = shrink(s, r, k, last, i)?;
                 }
             }
             LayerContent::Shape(t) => {
                 if let Some(s) = &mut t.cache {
-                    *s = shrink(s, r, k, i)?;
+                    *s = shrink(s, r, k, last, i)?;
                 }
             }
             LayerContent::Smart(t) => {
                 if let Some(s) = &mut t.cache {
-                    *s = shrink(s, r, k, i)?;
+                    *s = shrink(s, r, k, last, i)?;
                 }
             }
             _ => {}
@@ -84,10 +91,10 @@ pub fn preview_page(doc: &Document, source: Rect, factor: u32, interrupt: Interr
     let mut p = doc.clone();
     p.size = photocraft_doc::Size::new(doc.size.width.div_ceil(factor), doc.size.height.div_ceil(factor));
     for l in &mut p.layers {
-        layer(l, rect, k, interrupt, 0)?;
+        layer(l, rect, k, interrupt, 0, last)?;
     }
     for c in &mut p.channels {
-        c.surface = shrink(&c.surface, rect, k, interrupt)?;
+        c.surface = shrink(&c.surface, rect, k, last, interrupt)?;
     }
     interrupt.check().map_err(|e| e.to_string())?;
     Ok(render(&p, rect))
@@ -200,6 +207,22 @@ mod tests {
             }
         }
     }
+    /// A partial cell at the document's right and bottom edges samples the last document pixel,
+    /// not the layer's (transparent) default past it (#5332 review).
+    #[test]
+    fn preview_edge_cells_sample_inside_the_document() {
+        let mut d = Document::new("edge", Size::new(10, 10), ColorMode::Rgb, SampleType::U8);
+        let mut s = photocraft_raster::Surface::new(d.pixel_format());
+        s.fill_rect(d.bounds(), &[1.0, 0.0, 0.0, 1.0]);
+        d.layers.push(photocraft_doc::Layer::new("red", photocraft_doc::LayerContent::Raster(s)));
+        for source in [d.bounds(), Rect::new(4, 4, 10, 10)] {
+            let p = preview_page(&d, source, 4, Interrupt::NONE).unwrap();
+            assert_eq!(p.rect, Rect::new(source.x0 / 4, source.y0 / 4, 3, 3));
+            for (i, px) in p.px.iter().enumerate() {
+                assert!((px[0] - 1.0).abs() < 1e-6 && (px[3] - 1.0).abs() < 1e-6, "{source:?} cell {i}: {px:?}");
+            }
+        }
+    }
     /// A white document with a noisy, partly transparent layer and a multiplied solid over one-colour
     /// tiles, so the reduced path takes both its one-colour and per-pixel branches.
     fn busy(depth: SampleType) -> Document {

From ef79ba04ebe33e76f1c3a6deb97165dc61fc51e0 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 13:59:12 +0100
Subject: [PATCH 094/109] Viewport preview: keep artboard cells whose sample is
 on the board

The preview mapped artboard edges with div_euclid, so a board edge in the
second half of a cell dropped (upper edge) or kept (lower edge) a cell
against its sample at c*k + k/2, and a board narrower than a cell could
vanish. Map each edge to the first cell sampling at or after it.

Addresses CodeRabbit review r4454088367 on #5332.
---
 crates/compose/src/viewport.rs | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/crates/compose/src/viewport.rs b/crates/compose/src/viewport.rs
index fe4db1551b..40a6accee9 100644
--- a/crates/compose/src/viewport.rs
+++ b/crates/compose/src/viewport.rs
@@ -63,7 +63,13 @@ pub fn preview_page(doc: &Document, source: Rect, factor: u32, interrupt: Interr
             LayerContent::Raster(s) => *s = shrink(s, r, k, last, i)?,
             LayerContent::Group(g) => {
                 if let Some(a) = &mut g.artboard {
-                    a.rect = Rect::new(a.rect.x0.div_euclid(k), a.rect.y0.div_euclid(k), a.rect.x1.div_euclid(k), a.rect.y1.div_euclid(k));
+                    // A cell is on the board when its sample `c·k + k/2` is: each edge maps to the
+                    // first cell sampling at or after it.
+                    let edge = |e: i32| {
+                        let (s, k) = (i64::from(e) - i64::from(k / 2), i64::from(k));
+                        (s.div_euclid(k) + i64::from(s.rem_euclid(k) != 0)) as i32
+                    };
+                    a.rect = Rect::new(edge(a.rect.x0), edge(a.rect.y0), edge(a.rect.x1), edge(a.rect.y1));
                 }
                 for c in &mut g.children {
                     layer(c, r, k, i, depth + 1, last)?;
@@ -223,6 +229,24 @@ mod tests {
             }
         }
     }
+    /// An artboard covers the preview cells whose sample (`c·k + k/2`) lies on the board, so a
+    /// narrow board, or one whose edges fall mid-cell, keeps exactly those cells (#5332 review).
+    #[test]
+    fn preview_artboard_covers_the_cells_it_samples() {
+        let k = 4;
+        // (board x0..x1, cells expected on it); cell c samples x = 4c + 2.
+        for (x0, x1, on) in [(2, 3, 0..1), (0, 3, 0..1), (3, 16, 1..4), (1, 7, 0..2), (4, 14, 1..3), (-6, 6, 0..1), (-6, 7, 0..2)] {
+            let mut d = Document::new("boards", Size::new(16, 4), ColorMode::Rgb, SampleType::U8);
+            let board = photocraft_doc::Artboard::new(Rect::new(x0, 0, x1, 4));
+            let group = photocraft_doc::Group { children: vec![], expanded: true, artboard: Some(board), frame_stroke: None };
+            d.layers.push(photocraft_doc::Layer::new("board", photocraft_doc::LayerContent::Group(group)));
+            let p = preview_page(&d, d.bounds(), k, Interrupt::NONE).unwrap();
+            assert_eq!(p.rect, Rect::new(0, 0, 4, 1));
+            for (c, px) in p.px.iter().enumerate() {
+                assert_eq!(px[3] > 0.5, on.contains(&c), "board {x0}..{x1}, cell {c}: {px:?}");
+            }
+        }
+    }
     /// A white document with a noisy, partly transparent layer and a multiplied solid over one-colour
     /// tiles, so the reduced path takes both its one-colour and per-pixel branches.
     fn busy(depth: SampleType) -> Document {

From dadc6a8d5f29a5445fc39dbf7b175d42e667d46c Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 14:02:36 +0100
Subject: [PATCH 095/109] Viewport pages: fall back when an edited page fails
 to render

stuck() only counted a failed page as a hole when no page was held, so a
dirty (edited) page whose new render failed kept drawing its pre-edit
content until a retry. Treat a held dirty page like a missing one.

Addresses CodeRabbit review r4453118133 on #5332.
---
 crates/ui-egui/src/canvas/viewport_pages.rs | 23 ++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/crates/ui-egui/src/canvas/viewport_pages.rs b/crates/ui-egui/src/canvas/viewport_pages.rs
index 72483f9c0e..01c7d791cf 100644
--- a/crates/ui-egui/src/canvas/viewport_pages.rs
+++ b/crates/ui-egui/src/canvas/viewport_pages.rs
@@ -396,10 +396,11 @@ impl Stream {
         }
     }
 
-    /// Whether a wanted page can't be shown: its render or upload failed and nothing older of it
-    /// is held, so the view would have a hole (the CPU canvas draws instead).
+    /// Whether a wanted page can't be shown: its render or upload failed and nothing current of
+    /// it is held, so the view would have a hole, or keep showing the page from before an edit
+    /// (the CPU canvas draws instead).
     pub fn stuck(&self, wanted: &[PageId]) -> bool {
-        wanted.iter().any(|p| !self.pages.contains_key(p) && self.failed.contains(&(*p, self.epoch(*p))))
+        wanted.iter().any(|p| self.pages.get(p).is_none_or(|q| q.dirty) && self.failed.contains(&(*p, self.epoch(*p))))
     }
 
     /// Whether work is outstanding (the view repaints until it is done).
@@ -926,6 +927,22 @@ mod tests {
         assert!(!s.stuck(&view));
     }
 
+    /// An edited page whose new render fails isn't left showing its old content (#5332 review).
+    #[test]
+    fn a_dirty_page_whose_render_failed_falls_back() {
+        let view = [page(1, 0, 0)];
+        let mut s = holding(&view);
+        s.invalidate(id(2), None);
+        assert!(s.pages[&view[0]].dirty && !s.stuck(&view), "the old page shows while it renders");
+        let mut log = Vec::new();
+        s.update(&view, true, recorder(&mut log));
+        s.tx.send(Done { page: view[0], epoch: log[0].1, exact: true, region: None, result: Err("out of memory".into()) }).unwrap();
+        s.update(&view, true, |_, _, _, _, _| panic!("no retry while failed"));
+        assert!(s.stuck(&view), "a stale page is not drawn in place of the failed one");
+        s.retry_after((7, 7));
+        assert!(!s.stuck(&view));
+    }
+
     #[test]
     fn prune_drops_finer_and_dirty_pages_once_the_view_is_current() {
         let (fine, coarse, view) = (page(1, 0, 0), page(4, 0, 0), page(2, 0, 0));

From e291eef6d6e7753a52fdf0afb1a56a91c2e5acd7 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 14:03:59 +0100
Subject: [PATCH 096/109] Viewport pages: free a document's pages when no page
 fits the budget

With a canvas budget too small for one page, show() returned to the CPU
canvas after creating or invalidating the stream but before pruning, so
the stream's GPU pages and its jobs stayed held. Check the page budget
first and drop the stream and its pages, as a document that fits does.

Addresses CodeRabbit review r4453118176 on #5332.
---
 .../src/canvas/background_redraw/tests.rs     |  3 +++
 crates/ui-egui/src/canvas/viewport_pages.rs   | 24 ++++++++++++-------
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/crates/ui-egui/src/canvas/background_redraw/tests.rs b/crates/ui-egui/src/canvas/background_redraw/tests.rs
index a5397c77dd..a669b18a38 100644
--- a/crates/ui-egui/src/canvas/background_redraw/tests.rs
+++ b/crates/ui-egui/src/canvas/background_redraw/tests.rs
@@ -687,6 +687,9 @@ fn a_canvas_over_the_texture_budget_draws_its_viewport_pages_on_the_gpu() {
     gpu.set_canvas_budget(1);
     g.harness.run_steps(3);
     assert_eq!(render_path_of(&g), (Some("canvasTooLarge"), Some("CPU Rendering")));
+    // Its pages and their work are freed meanwhile (#5332 review).
+    assert!(gpu.pages(key).0.is_empty(), "pages freed");
+    assert!(!g.harness.state().streams.contains_key(&doc.id), "stream dropped");
     gpu.set_canvas_budget(set - 1);
     settle_pages(&mut g);
     // Closing the document cancels its work and frees its pages.
diff --git a/crates/ui-egui/src/canvas/viewport_pages.rs b/crates/ui-egui/src/canvas/viewport_pages.rs
index 01c7d791cf..410a7d4dfc 100644
--- a/crates/ui-egui/src/canvas/viewport_pages.rs
+++ b/crates/ui-egui/src/canvas/viewport_pages.rs
@@ -597,6 +597,20 @@ pub(super) fn show(app: &mut PhotocraftApp, ctx: &egui::Context, idx: usize, xf:
         }
         return false;
     }
+    let key = stream_key(id.0);
+    // Half the per-document canvas budget: the rest is headroom for what the compositor needs.
+    let limit = gpu.canvas_budget() / 2;
+    let page_bytes = gpu.page_texture_bytes(doc.depth, size, PAGE_SIDE + 2, PAGE_SIDE + 2).max(1);
+    let max_pages = usize::try_from(limit / page_bytes).unwrap_or(usize::MAX);
+    // No room for a single page: the CPU canvas draws the document, as main does for every
+    // document over the budget, and the pages and work held for it are freed.
+    if max_pages == 0 {
+        if let Some(s) = app.streams.remove(&id) {
+            drop(s);
+            gpu.retain_pages(key, &[]);
+        }
+        return false;
+    }
     let (display, _) = canvas_display(app, &doc, None);
     let display_key = texture_key(display.as_deref());
     let now = Identity { revision, preview: raw_key, display: display_key, size };
@@ -607,11 +621,6 @@ pub(super) fn show(app: &mut PhotocraftApp, ctx: &egui::Context, idx: usize, xf:
             .and_then(|s| damage_since(app, idx, (s.revision, s.preview ^ display_key), (revision, raw_key), display_key, last_damage));
         app.streams.entry(id).or_default().invalidate(now, damage);
     }
-    let key = stream_key(id.0);
-    // Half the per-document canvas budget: the rest is headroom for what the compositor needs.
-    let limit = gpu.canvas_budget() / 2;
-    let page_bytes = gpu.page_texture_bytes(doc.depth, size, PAGE_SIDE + 2, PAGE_SIDE + 2).max(1);
-    let max_pages = usize::try_from(limit / page_bytes).unwrap_or(usize::MAX);
     let wanted = pages(size, visible_doc_rect(xf), zoom, max_pages);
     if gpu.texture_info(id.0).is_some() {
         // Switching from the texture set: free it, the pages are budgeted against that memory.
@@ -619,9 +628,8 @@ pub(super) fn show(app: &mut PhotocraftApp, ctx: &egui::Context, idx: usize, xf:
     }
     let stream = app.streams.entry(id).or_default();
     stream.retry_after((photocraft_raster::spill::read_error_generation(), photocraft_raster::memory::configuration_generation()));
-    // No room for a single page, or a page that failed: the CPU canvas draws the document, as
-    // main does for every document over the budget.
-    if max_pages == 0 || stream.stuck(&wanted) {
+    // A page that failed: the CPU canvas draws the document until it is retried.
+    if stream.stuck(&wanted) {
         return false;
     }
     let faithful = photocraft_compose::proxy::proxy_faithful(&doc);

From 0a97fa7f75a749877ca26b7e0bbbd8ca7f4130e1 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 14:06:05 +0100
Subject: [PATCH 097/109] GPU canvas: catch errors creating or writing a
 viewport page

upload_page created the page texture, uniform buffer and bind group and
wrote the texels with no error scope, so an out-of-memory error there
reached the uncaptured-error handler and disabled the GPU canvas for the
session. Share DocTextures::new's validation/out-of-memory scopes as
catch_gpu_errors and run the page work inside them: a refused page
fails alone (the view falls back to the CPU canvas) and the device stays
usable.

Addresses CodeRabbit review r4453118114 on #5332.
---
 .../src/canvas/gpu_canvas/doc_textures.rs     | 30 ++++++---
 .../src/canvas/gpu_canvas/mip_tests.rs        | 31 +++++++++
 crates/ui-egui/src/canvas/gpu_canvas/pages.rs | 67 +++++++++++--------
 3 files changed, 90 insertions(+), 38 deletions(-)

diff --git a/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs b/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
index 155bb21c91..e21efd41ca 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
@@ -44,6 +44,24 @@ pub(super) fn tile_uniform([x, y, w, h]: [u32; 4], core: Option<[i32; 4]>) -> [f
     [x as f32, y as f32, w as f32, h as f32, cx0, cy0, cx1, cy1]
 }
 
+/// Run `f` with its validation and out-of-memory errors caught, rather than reaching the
+/// device's uncaptured-error handler (which takes the GPU canvas down for the session): what `f`
+/// returned, and the first error. Native wgpu reports these synchronously; where they arrive
+/// later (WebGPU) none is seen.
+pub(super) fn catch_gpu_errors<T>(device: &wgpu::Device, f: impl FnOnce() -> T) -> (T, Option<wgpu::Error>) {
+    let validation = device.push_error_scope(wgpu::ErrorFilter::Validation);
+    let memory = device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
+    let out = f();
+    let mut cx = std::task::Context::from_waker(std::task::Waker::noop());
+    let mut error = None;
+    for pop in [memory.pop(), validation.pop()] {
+        if let std::task::Poll::Ready(Some(e)) = std::pin::pin!(pop).poll(&mut cx) {
+            error.get_or_insert(e);
+        }
+    }
+    (out, error)
+}
+
 impl DocTextures {
     /// The texture set for a `size` canvas, or `None` (nothing created) when it doesn't fit
     /// the canvas budget or the GPU's memory. A set the GPU can't hold (a 3 GP canvas is 16 GB
@@ -54,17 +72,7 @@ impl DocTextures {
         if bytes > res.canvas_budget.load(Ordering::Relaxed) {
             return None;
         }
-        let validation = device.push_error_scope(wgpu::ErrorFilter::Validation);
-        let memory = device.push_error_scope(wgpu::ErrorFilter::OutOfMemory);
-        let set = Self::create(device, res, size, tile, format);
-        // Native wgpu reports these synchronously; where they arrive later (WebGPU) none is seen.
-        let mut cx = std::task::Context::from_waker(std::task::Waker::noop());
-        let mut error = None;
-        for pop in [memory.pop(), validation.pop()] {
-            if let std::task::Poll::Ready(Some(e)) = std::pin::pin!(pop).poll(&mut cx) {
-                error.get_or_insert(e);
-            }
-        }
+        let (set, error) = catch_gpu_errors(device, || Self::create(device, res, size, tile, format));
         if let Some(e) = error {
             log::warn!("{} MB of canvas textures failed ({e}); larger canvases are drawn on the CPU", bytes >> 20);
             res.canvas_budget.fetch_min(bytes.saturating_sub(1), Ordering::Relaxed);
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/mip_tests.rs b/crates/ui-egui/src/canvas/gpu_canvas/mip_tests.rs
index feb0df375e..8de45748b6 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/mip_tests.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/mip_tests.rs
@@ -66,6 +66,37 @@ fn canvas_mips_preserve_opaque_pixels_and_partial_updates() {
     }
     // On the same device (see the top of the file).
     canvas_textures_the_gpu_refuses_leave_it_working(&gpu);
+    refused_viewport_page_work_is_caught(&gpu);
+}
+
+/// #5332 review: viewport page uploads run their texture, buffer and bind group creation and
+/// their write inside the same error scopes as a texture set, so an error the GPU raises there
+/// (out of memory, in use) is returned instead of disabling the GPU for the session. A texture
+/// wider than the device allows is refused the same way, synchronously, on any adapter.
+fn refused_viewport_page_work_is_caught(gpu: &GpuCanvas) {
+    let device = &gpu.rs.device;
+    let max = device.limits().max_texture_dimension_2d;
+    let (texture, error) = super::doc_textures::catch_gpu_errors(device, || {
+        device.create_texture(&wgpu::TextureDescriptor {
+            label: Some("too_wide_page"),
+            size: wgpu::Extent3d { width: max + 1, height: 1, depth_or_array_layers: 1 },
+            mip_level_count: 1,
+            sample_count: 1,
+            dimension: wgpu::TextureDimension::D2,
+            format: FORMAT,
+            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
+            view_formats: &[],
+        })
+    });
+    drop(texture);
+    assert!(error.is_some(), "the refusal is caught");
+    assert!(gpu.health.is_ok(), "{:?}", gpu.fault());
+    // A page the GPU accepts is stored as before.
+    let buf = Buffer::filled(Rect::from_xywh(0, 0, 64, 64), [0.5, 0.5, 0.5, 1.0]);
+    let core = Rect::new(1, 1, 63, 63);
+    assert!(gpu.upload_page(PageUpload { key: 9, page: 1, size: [64, 64], depth: SampleType::U8, factor: 1, core, buf: &buf }));
+    assert_eq!(gpu.pages(9).0, vec![1]);
+    assert!(gpu.health.is_ok(), "{:?}", gpu.fault());
 }
 
 /// #4017: a 3 GP canvas's 16 GB of textures failed with Out of Memory, and the uncaptured error
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/pages.rs b/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
index b5f9fe7e7d..05ff59ee40 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
@@ -2,7 +2,7 @@
 //! `canvas::viewport_pages`): independent single-level textures at their own reduction, drawn
 //! by the same tile pipeline. They live under their own key, never next to a texture set.
 
-use super::doc_textures::{init_buffer, tile_uniform};
+use super::doc_textures::{catch_gpu_errors, init_buffer, tile_uniform};
 use super::resources::{DocTextures, Resources, Tile, f32_bytes};
 use super::texels::{texel_bytes, texels};
 use super::{GpuCanvas, Ordering, wgpu};
@@ -108,34 +108,47 @@ impl GpuCanvas {
         if held.saturating_add(bytes) > budget {
             return false;
         }
-        let texture = device.create_texture(&wgpu::TextureDescriptor {
-            label: Some("pc_viewport_page"),
-            size: wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
-            mip_level_count: 1,
-            sample_count: 1,
-            dimension: wgpu::TextureDimension::D2,
-            format,
-            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
-            view_formats: &[],
-        });
-        let view = texture.create_view(&Default::default());
         let rect = [x, y, dw, dh];
-        let uniform =
-            init_buffer(device, "pc_viewport_page", &f32_bytes(&tile_uniform(rect, Some([core.x0, core.y0, core.x1, core.y1]))), wgpu::BufferUsages::UNIFORM);
-        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
-            label: Some("pc_viewport_page"),
-            layout: &res.tile_bgl,
-            entries: &[
-                wgpu::BindGroupEntry { binding: 0, resource: wgpu::BindingResource::TextureView(&view) },
-                wgpu::BindGroupEntry { binding: 1, resource: uniform.as_entire_binding() },
-            ],
+        // A page the GPU refuses (out of memory) fails alone: it falls back to the CPU canvas
+        // instead of the uncaptured error disabling the GPU canvas for the session.
+        let ((texture, view, uniform, bind_group), error) = catch_gpu_errors(device, || {
+            let texture = device.create_texture(&wgpu::TextureDescriptor {
+                label: Some("pc_viewport_page"),
+                size: wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
+                mip_level_count: 1,
+                sample_count: 1,
+                dimension: wgpu::TextureDimension::D2,
+                format,
+                usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
+                view_formats: &[],
+            });
+            let view = texture.create_view(&Default::default());
+            let uniform = init_buffer(
+                device,
+                "pc_viewport_page",
+                &f32_bytes(&tile_uniform(rect, Some([core.x0, core.y0, core.x1, core.y1]))),
+                wgpu::BufferUsages::UNIFORM,
+            );
+            let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
+                label: Some("pc_viewport_page"),
+                layout: &res.tile_bgl,
+                entries: &[
+                    wgpu::BindGroupEntry { binding: 0, resource: wgpu::BindingResource::TextureView(&view) },
+                    wgpu::BindGroupEntry { binding: 1, resource: uniform.as_entire_binding() },
+                ],
+            });
+            queue.write_texture(
+                texture.as_image_copy(),
+                &texels(format, &buf.px),
+                wgpu::TexelCopyBufferLayout { offset: 0, bytes_per_row: Some(w * texel_bytes(format) as u32), rows_per_image: Some(h) },
+                wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
+            );
+            (texture, view, uniform, bind_group)
         });
-        queue.write_texture(
-            texture.as_image_copy(),
-            &texels(format, &buf.px),
-            wgpu::TexelCopyBufferLayout { offset: 0, bytes_per_row: Some(w * texel_bytes(format) as u32), rows_per_image: Some(h) },
-            wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
-        );
+        if let Some(e) = error {
+            log::warn!("a {w}×{h} viewport page couldn't be stored on the GPU: {e}");
+            return false;
+        }
         let Some(d) = res.docs.get_mut(&key) else { return false };
         if let Some(i) = replaced {
             d.tiles.remove(i);

From 64c638568490df7b3d1e2189a38ef007f9f204e1 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 14:08:50 +0100
Subject: [PATCH 098/109] Viewport pages: keep the pages another window on the
 document shows

Two windows can show one document (Window > Arrange > New Window for
Document) and share its stream, but each frame treated only its own
wanted pages as live: it cancelled the other window's jobs, dropped its
finished results, evicted its pages first and pruned them as finer than
its own view, so the windows undid each other's work every frame.

Record each window's wanted pages by viewport id. Jobs and results for
any window's pages are kept, pruning skips them, and eviction takes
pages no window shows before another window's. A window not seen for
VIEW_TTL updates (closed) releases them. With one window nothing
changes.

Addresses CodeRabbit review r4453118205 on #5332.
---
 crates/ui-egui/src/canvas/viewport_pages.rs | 88 ++++++++++++++++++++-
 1 file changed, 84 insertions(+), 4 deletions(-)

diff --git a/crates/ui-egui/src/canvas/viewport_pages.rs b/crates/ui-egui/src/canvas/viewport_pages.rs
index 410a7d4dfc..e05455d51b 100644
--- a/crates/ui-egui/src/canvas/viewport_pages.rs
+++ b/crates/ui-egui/src/canvas/viewport_pages.rs
@@ -209,6 +209,10 @@ pub(crate) struct Stream {
     /// The page ids last given to the GPU canvas, to tell it only of changes.
     synced: Vec<u64>,
     health: (u64, u64),
+    /// Each window showing the document (New Window for Document): the clock of its last frame
+    /// and the pages it wanted, so one window's frame doesn't cancel, drop or evict the pages
+    /// another window still shows.
+    views: HashMap<u64, (u64, Vec<PageId>)>,
     pub stats: Stats,
 }
 
@@ -227,6 +231,7 @@ impl Default for Stream {
             clock: 0,
             synced: Vec::new(),
             health: (0, 0),
+            views: HashMap::new(),
             stats: Stats::default(),
         }
     }
@@ -317,13 +322,28 @@ impl Stream {
         }
     }
 
+    /// Window `view` is about to show `wanted` (call before [`Self::update`] in its frame).
+    pub fn view(&mut self, view: u64, wanted: &[PageId]) {
+        self.views.insert(view, (self.clock + 1, wanted.to_vec()));
+    }
+
+    /// Whether a window other than the one updating shows `page`: one whose frame was at most
+    /// [`VIEW_TTL`] updates ago (a closed window's pages are released after that).
+    fn shown_elsewhere(&self, page: &PageId) -> bool {
+        self.views.values().any(|(at, pages)| *at != self.clock && *at + VIEW_TTL >= self.clock && pages.contains(page))
+    }
+
     /// Take finished work, cancel work for pages not `wanted`, and start work for wanted pages
     /// that are missing, dirty or still a quick preview (`faithful`: the document has a quick
     /// preview at reductions), as `spawn(page, epoch, exact, cancel, region)` allows: `region`, the
     /// part of a held page to render again ([`Page::partial`]), or the whole page.
     pub fn update(&mut self, wanted: &[PageId], faithful: bool, mut spawn: impl FnMut(PageId, u64, bool, Arc<AtomicBool>, Option<DRect>) -> bool) {
         self.clock += 1;
-        let want: HashSet<PageId> = wanted.iter().copied().collect();
+        let clock = self.clock;
+        self.views.retain(|_, (at, _)| *at + VIEW_TTL >= clock);
+        // What any window shows: work and results for another window's pages are kept.
+        let want: HashSet<PageId> =
+            wanted.iter().copied().chain(self.views.values().filter(|(at, _)| *at != clock).flat_map(|(_, pages)| pages.iter().copied())).collect();
         while let Ok(d) = self.rx.try_recv() {
             let Some(i) = self.jobs.iter().position(|j| j.page == d.page && j.epoch == d.epoch) else { continue };
             // Cancelled work ends in an interruption, not a failure: the page is asked for again.
@@ -427,12 +447,18 @@ impl Stream {
     }
 
     /// Make room for `bytes` more under `limit` by evicting the least recently wanted pages not
-    /// in `wanted`: whether any was evicted, or `None` when the wanted pages leave no room.
+    /// in `wanted` (another window's last: they are only shown there): whether any was evicted,
+    /// or `None` when the wanted pages leave no room.
     pub fn make_room(&mut self, page: PageId, bytes: u64, limit: u64, wanted: &[PageId]) -> Option<bool> {
         let held = |s: &Self| s.pages.iter().filter(|(p, _)| **p != page).map(|(_, q)| q.bytes).sum::<u64>();
         let mut evicted = false;
         while held(self) + bytes > limit {
-            let cold = self.pages.iter().filter(|(p, _)| **p != page && !wanted.contains(p)).min_by_key(|(_, q)| q.touched).map(|(p, _)| *p)?;
+            let cold = self
+                .pages
+                .iter()
+                .filter(|(p, _)| **p != page && !wanted.contains(p))
+                .min_by_key(|(p, q)| (self.shown_elsewhere(p), q.touched))
+                .map(|(p, _)| *p)?;
             self.drop_page(cold);
             self.stats.evicted += 1;
             evicted = true;
@@ -483,7 +509,8 @@ impl Stream {
     pub fn prune(&mut self, wanted: &[PageId]) -> Option<Vec<u64>> {
         let all_current = wanted.iter().all(|p| self.pages.get(p).is_some_and(|q| !q.dirty));
         if all_current && let Some(f) = wanted.first().map(|p| p.factor) {
-            let drop: Vec<PageId> = self.pages.iter().filter(|(p, q)| !wanted.contains(p) && (q.dirty || p.factor < f)).map(|(p, _)| *p).collect();
+            let drop: Vec<PageId> =
+                self.pages.iter().filter(|(p, q)| !wanted.contains(p) && !self.shown_elsewhere(p) && (q.dirty || p.factor < f)).map(|(p, _)| *p).collect();
             for p in drop {
                 self.drop_page(p);
             }
@@ -507,6 +534,9 @@ impl Stream {
     }
 }
 
+/// How many stream updates a window's pages stay protected after its last frame.
+const VIEW_TTL: u64 = 64;
+
 /// Render `page` of `doc` on a worker, if one of the [`MAX_JOBS`] is free.
 fn spawn(
     ctx: &egui::Context,
@@ -646,6 +676,7 @@ pub(super) fn show(app: &mut PhotocraftApp, ctx: &egui::Context, idx: usize, xf:
     app.navigator_gpu.remove(&id);
     crate::render_path::note(app, id.0, crate::render_path::Path::Gpu { full: true });
     let stream = app.streams.entry(id).or_default();
+    stream.view(ctx.viewport_id().0.value(), &wanted);
     let tx = stream.tx.clone();
     stream.update(&wanted, faithful, |page, epoch, exact, cancel, region| {
         spawn(ctx, tx.clone(), doc.clone(), display.clone(), (page, epoch, exact, region), cancel)
@@ -951,6 +982,55 @@ mod tests {
         assert!(!s.stuck(&view));
     }
 
+    /// #5332 review: two windows showing one document (New Window for Document) share its
+    /// stream. One window's frame doesn't cancel the other's work, drop its results, evict its
+    /// pages or prune them as finer than its own view; a window gone for a while releases them.
+    #[test]
+    fn windows_on_one_document_keep_each_others_pages() {
+        let (a, b) = ([page(1, 0, 0)], [page(4, 0, 0)]);
+        let mut s = holding(&[]);
+        let (mut log_a, mut log_b) = (Vec::new(), Vec::new());
+        s.view(1, &a);
+        s.update(&a, true, recorder(&mut log_a));
+        s.view(2, &b);
+        s.update(&b, false, recorder(&mut log_b));
+        assert!(!log_a[0].3.load(Ordering::Relaxed), "window 2's frame keeps window 1's work");
+        // Window 1's page finishes during window 2's frame: it is kept for upload.
+        s.tx.send(done(a[0], log_a[0].1, true, 4)).unwrap();
+        s.view(2, &b);
+        s.update(&b, false, |_, _, _, _, _| true);
+        assert!(s.ready.iter().any(|d| d.page == a[0]), "window 1's result is kept");
+        for d in s.take_uploads(&b, 16) {
+            s.uploaded(&d, 100, true);
+        }
+        s.tx.send(done(b[0], log_b[0].1, true, 4)).unwrap();
+        s.view(2, &b);
+        s.update(&b, false, |_, _, _, _, _| true);
+        for d in s.take_uploads(&b, 16) {
+            s.uploaded(&d, 100, true);
+        }
+        assert_eq!(s.resident(), 2);
+        // Window 2's view is current: window 1's finer page isn't pruned, nor evicted first.
+        s.prune(&b);
+        assert!(s.pages.contains_key(&a[0]), "not pruned while window 1 shows it");
+        s.pages.insert(page(4, 1, 0), Page { dirty: false, exact: true, partial: None, epoch: 0, touched: s.clock, bytes: 100 });
+        assert_eq!(s.make_room(page(4, 2, 0), 100, 300, &b), Some(true));
+        assert!(s.pages.contains_key(&a[0]) && !s.pages.contains_key(&page(4, 1, 0)), "a page no window shows goes first");
+        // Window 1 closed: once its pages are past the grace period, window 2 prunes them.
+        for _ in 0..=VIEW_TTL {
+            s.view(2, &b);
+            s.update(&b, false, |_, _, _, _, _| true);
+        }
+        s.prune(&b);
+        assert!(!s.pages.contains_key(&a[0]), "released after the closed window's grace period");
+        // Without a recorded window (one view), nothing changes: other pages are cancelled.
+        let mut s = holding(&[]);
+        let mut log = Vec::new();
+        s.update(&a, true, recorder(&mut log));
+        s.update(&b, true, |_, _, _, _, _| true);
+        assert!(log[0].3.load(Ordering::Relaxed));
+    }
+
     #[test]
     fn prune_drops_finer_and_dirty_pages_once_the_view_is_current() {
         let (fine, coarse, view) = (page(1, 0, 0), page(4, 0, 0), page(2, 0, 0));

From a0418a2e29e12c6f50d64e07083a5a96d5205fbf Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 14:50:52 +0100
Subject: [PATCH 099/109] Address CodeRabbit review: Batch failures, late Esc,
 CLI format, bridge result

- A failed input stays in `errors` when `jobs.cancel` or Esc lands while it runs, instead of
  showing up as skipped without its reason.
- Esc after the last input is refused: the worker closes the interrupt window once no
  checkpoint is left, so `request_batch_interrupt` no longer answers true for a question
  that never comes.
- `photocraft-cli batch` without `--format` saves a file PhotoCraft only opens as PSD, the
  format `--naming`'s {ext} already plans, instead of asking the encoder for the input's
  import-only extension.
- `--recursive` help says the output is flat.
- The app bridge keeps a cancelled Batch's partial result in the error it returns to MCP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/photocraft-cli/src/args.rs              |  3 +-
 apps/photocraft-cli/src/batch.rs             |  6 +-
 apps/photocraft-cli/tests/it/cli.rs          | 31 +++++++++
 crates/automation/src/bridge.rs              | 31 +++++++--
 crates/engine/src/cmd/file_cmds.rs           |  4 +-
 crates/engine/src/cmd/file_cmds/batch_run.rs | 32 +++++++--
 crates/engine/src/cmd/file_cmds/tests.rs     | 72 ++++++++++++++++++++
 crates/engine/src/jobs.rs                    |  9 +++
 docs/control-protocol.md                     |  2 +-
 9 files changed, 174 insertions(+), 16 deletions(-)

diff --git a/apps/photocraft-cli/src/args.rs b/apps/photocraft-cli/src/args.rs
index b582b32c59..c94a4bb8cd 100644
--- a/apps/photocraft-cli/src/args.rs
+++ b/apps/photocraft-cli/src/args.rs
@@ -182,7 +182,8 @@ pub(crate) struct BatchArgs {
     /// originals; --in-place allows it
     #[arg(long)]
     pub(crate) in_place: bool,
-    /// Include images in subfolders and mirror their folders under --out
+    /// Include images in subfolders; every result goes straight into --out, so a later file of
+    /// the same name replaces an earlier one
     #[arg(long)]
     pub(crate) recursive: bool,
     /// Name each result with Batch tokens such as {name}, {serial}, {date}, and {ext}
diff --git a/apps/photocraft-cli/src/batch.rs b/apps/photocraft-cli/src/batch.rs
index c096d8100d..347f829443 100644
--- a/apps/photocraft-cli/src/batch.rs
+++ b/apps/photocraft-cli/src/batch.rs
@@ -93,7 +93,7 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
             .iter()
             .map(|input| {
                 let path = Path::new(&input.path);
-                let ext = format.map(str::to_owned).or_else(|| path.extension().map(|e| e.to_string_lossy().into_owned())).unwrap_or_else(|| "png".into());
+                let ext = format.map_or_else(|| photocraft_engine::file_cmds::batch_same_format(&input.path), str::to_owned);
                 let stem = path.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_default();
                 out_dir.join(format!("{stem}.{ext}"))
             })
@@ -112,7 +112,9 @@ pub(crate) fn batch(a: &BatchArgs, out: &mut dyn Write, err: &mut dyn Write) ->
     for (input, target) in inputs.iter().zip(targets) {
         let input = Path::new(&input.path);
         // The selected format encodes the bytes, whatever extension `--naming` gives the file.
-        let ext = format.map(str::to_owned).or_else(|| input.extension().map(|e| e.to_string_lossy().into_owned())).unwrap_or_else(|| "png".into());
+        // Without --format, a file PhotoCraft only opens (.kra, raw, …) is saved as PSD, the
+        // same format `--naming`'s {ext} plans.
+        let ext = format.map_or_else(|| photocraft_engine::file_cmds::batch_same_format(&input.to_string_lossy()), str::to_owned);
         let r = (|| -> Result<Vec<String>> {
             if let Some(parent) = target.parent() {
                 std::fs::create_dir_all(parent)?;
diff --git a/apps/photocraft-cli/tests/it/cli.rs b/apps/photocraft-cli/tests/it/cli.rs
index 4dac055d2f..cafe35b804 100644
--- a/apps/photocraft-cli/tests/it/cli.rs
+++ b/apps/photocraft-cli/tests/it/cli.rs
@@ -556,6 +556,37 @@ fn batch_naming_keeps_the_tree_order_and_the_selected_encoder() {
     std::fs::remove_dir_all(root).unwrap();
 }
 
+/// Without --format, a file PhotoCraft only opens is saved as PSD, with or without --naming:
+/// the encoder gets the format the planned name uses, not the input's import-only extension.
+#[test]
+fn batch_saves_import_only_inputs_as_psd() {
+    let root = tmp("batch-import-only");
+    let input = root.join("in");
+    std::fs::create_dir_all(&input).unwrap();
+    std::fs::write(
+        input.join("logo.xpm"),
+        "/* XPM */
+static char *logo[] = {
+\"2 2 1 1\",
+\"a c #FF0000\",
+\"aa\",
+\"aa\"
+};
+",
+    )
+    .unwrap();
+    let actions = root.join("actions.json");
+    std::fs::write(&actions, "[]").unwrap();
+    for (name, extra) in [("plain", &[][..]), ("named", &["--naming", "{name}.{ext}"][..])] {
+        let out = root.join(name);
+        let result = bin().args(["batch", "--actions"]).arg(&actions).arg("--in").arg(&input).arg("--out").arg(&out).args(extra).output().unwrap();
+        assert!(result.status.success(), "{name}: {}{}", String::from_utf8_lossy(&result.stdout), String::from_utf8_lossy(&result.stderr));
+        assert!(std::fs::read(out.join("logo.psd")).unwrap().starts_with(b"8BPS"), "{name}: PSD bytes");
+        assert!(!out.join("logo.xpm").exists(), "{name}");
+    }
+    std::fs::remove_dir_all(root).unwrap();
+}
+
 #[test]
 fn batch_skips_recorded_view_and_save_steps() {
     let d = tmp("batch-shell-steps");
diff --git a/crates/automation/src/bridge.rs b/crates/automation/src/bridge.rs
index 5c238a3b51..adb6d8eea6 100644
--- a/crates/automation/src/bridge.rs
+++ b/crates/automation/src/bridge.rs
@@ -227,18 +227,39 @@ async fn exchange(conn: &mut Conn, id: u64, method: &str, params: &Value) -> Res
         if v.get("id").and_then(Value::as_u64) != Some(id) {
             continue; // stale reply from an earlier, timed-out request
         }
-        return Ok(if v.get("ok").and_then(Value::as_bool) == Some(true) {
-            Ok(v.get("result").cloned().unwrap_or(Value::Null))
-        } else {
-            Err(AutomationError::App(v.get("error").and_then(Value::as_str).unwrap_or("unknown error").to_owned()))
-        });
+        return Ok(reply_result(&v));
     }
 }
 
+/// An app reply as the caller's result. A failed reply can still carry a `result`: a cancelled
+/// Batch lists the outputs it already wrote, so the error keeps it rather than dropping it.
+fn reply_result(v: &Value) -> Result<Value, AutomationError> {
+    if v.get("ok").and_then(Value::as_bool) == Some(true) {
+        return Ok(v.get("result").cloned().unwrap_or(Value::Null));
+    }
+    let error = v.get("error").and_then(Value::as_str).unwrap_or("unknown error");
+    Err(AutomationError::App(match v.get("result") {
+        Some(result) if !result.is_null() => format!("{error}; partial result: {result}"),
+        _ => error.to_owned(),
+    }))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn a_failed_reply_keeps_its_partial_result() {
+        assert_eq!(reply_result(&json!({"ok": true, "result": {"files": ["a.png"]}})).unwrap(), json!({"files": ["a.png"]}));
+        let Err(AutomationError::App(message)) = reply_result(&json!({"ok": false, "error": "cancelled", "result": {"files": ["a.png"], "cancelled": true}}))
+        else {
+            panic!("a failed reply is an app error")
+        };
+        assert!(message.starts_with("cancelled; partial result: ") && message.contains("a.png"), "{message}");
+        let Err(AutomationError::App(message)) = reply_result(&json!({"ok": false, "error": "cancelled"})) else { panic!("a failed reply is an app error") };
+        assert_eq!(message, "cancelled");
+    }
+
     #[test]
     fn the_call_timeout_stays_below_the_app_reply_deadline() {
         // At or above the app's 60s deadline, callers would see their own cutoff first.
diff --git a/crates/engine/src/cmd/file_cmds.rs b/crates/engine/src/cmd/file_cmds.rs
index 96fc4719cc..611fdb0d60 100644
--- a/crates/engine/src/cmd/file_cmds.rs
+++ b/crates/engine/src/cmd/file_cmds.rs
@@ -31,10 +31,12 @@ mod save;
 pub use batch_naming::plan as plan_batch_names;
 #[cfg(test)]
 pub(crate) use batch_run::MAX_SUBFOLDER_DEPTH;
+use batch_run::batch;
+pub use batch_run::same_format as batch_same_format;
+use batch_run::same_format;
 #[cfg(not(target_arch = "wasm32"))]
 pub use batch_run::validate_flat_outputs;
 pub use batch_run::{BatchInput, OutputClaims, encode_batch_error_log, list_images_tree};
-use batch_run::{batch, same_format};
 pub(crate) use batch_run::{batch_inputs, batch_keeps_step, batch_save_point, process_files};
 pub use export::{LayerExportReport, SkippedExportLayer, bake_cube, export_layers_report_with, export_layers_with};
 use export::{color_lookup_tables, layers_to_files, push_unique};
diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 7d62d16f45..5a93e670a8 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -143,7 +143,9 @@ pub(crate) fn process_tree(
 /// codec formats without a writer in this build. Those are saved as PSD, the format Photoshop's
 /// Save As offers for a raw. An input whose file name has no extension (a dot in a folder name
 /// doesn't count) is saved as PNG.
-pub(super) fn same_format(path: &str) -> String {
+/// The format Batch's "Save in the same format" writes for `path`: its own, or PSD for a file
+/// PhotoCraft only opens.
+pub fn same_format(path: &str) -> String {
     const IMPORT_ONLY: &[&str] =
         &["pdn", "kra", "krz", "af", "afdesign", "afphoto", "afpub", "heic", "heif", "hif", "svg", "svgz", "cin", "pcx", "xpm", "xcf", "xcfgz", "gz", "psdt"];
     let ext = extension(path).unwrap_or_else(|| "png".into());
@@ -364,25 +366,41 @@ pub(super) fn process_batch_outputs(
         }
         ctx.progress(index as f32 / total.max(1) as f32, &format!("{} of {total}: {}", index + 1, file_name(path)));
         let result = process_one(raw_ppi, path, out, save, ProcessOptions { format: Some(format), written: None, ctx: Some(ctx) }, f);
+        // An input that failed on its own (not because it was stopped) stays a failure with its
+        // reason, even when a cancel or Esc lands while it runs.
+        let failure =
+            result.as_ref().err().filter(|error| !matches!(error, EngineError::Cancelled)).map(|error| json!({"file": path, "error": error.to_string()}));
         if ctx.cancelled() {
             ctx.publish_batch_preview(path, None);
             // A cancel that lands while the result is written still leaves that file written.
             if result.is_ok() {
                 files.push(out.clone());
                 done = index + 1;
+            } else if let Some(failure) = failure {
+                errors.push(failure);
+                done = index + 1;
             } else {
                 done = index;
             }
             break;
         }
         if ctx.batch_take_interrupt() {
-            if ctx.batch_wait_for_decision() {
-                ctx.publish_batch_preview(path, None);
-                interrupted.push(path.clone());
-                done = index + 1;
+            let continue_next = ctx.batch_wait_for_decision();
+            ctx.publish_batch_preview(path, None);
+            match failure {
+                Some(failure) => {
+                    errors.push(failure);
+                    done = index + 1;
+                }
+                None if continue_next => {
+                    interrupted.push(path.clone());
+                    done = index + 1;
+                }
+                None => {}
+            }
+            if continue_next {
                 continue;
             }
-            ctx.publish_batch_preview(path, None);
             ctx.cancel();
             break;
         }
@@ -402,6 +420,8 @@ pub(super) fn process_batch_outputs(
             }
         }
     }
+    // No checkpoint follows the last input: a later Esc has nothing to interrupt.
+    ctx.batch_close_interrupts();
     let log_failure = error_log_failure(policy.error_log.as_deref(), &errors);
     let cancelled = ctx.cancelled();
     if !cancelled {
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 53efd65782..7c49ed2151 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -89,6 +89,78 @@ fn batch_cancelled_during_an_action_does_not_save_that_input() {
     assert!(!std::path::Path::new(&out).exists());
 }
 
+/// A cancel that lands while an input fails on its own keeps that failure and its reason; only
+/// the inputs after it are skipped.
+#[test]
+fn batch_cancel_during_a_failing_input_keeps_its_error() {
+    let dir = tmp("batch-cancel-failing");
+    let first = png(&dir, "first.png", 8, 6, "#ff0000");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let ctx = crate::jobs::JobCtx::new();
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+    let outputs = vec![(first.clone(), join(&dir, "out/first.png")), (second.clone(), join(&dir, "out/second.png"))];
+    let result = super::batch_run::process_batch_outputs(72.0, outputs, "png", SaveOpts::default(), &policy, &ctx, &|_, _| {
+        ctx.cancel();
+        Err(EngineError::Other("boom".into()))
+    })
+    .unwrap();
+    assert_eq!(result["errors"], json!([{"file": first, "error": "boom"}]), "{result}");
+    assert_eq!(result["skipped"], json!([second]), "{result}");
+    assert_eq!(result["cancelled"], json!(true), "{result}");
+}
+
+/// Esc during an input that fails on its own: Continue records the failure (not an interrupted
+/// input) and goes on with the next one.
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn batch_interruption_during_a_failing_input_keeps_its_error() {
+    use std::time::Duration;
+
+    let dir = tmp("batch-interrupt-failing");
+    let first = png(&dir, "first.png", 8, 6, "#ff0000");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let second_out = join(&dir, "out/second.png");
+    let ctx = crate::jobs::JobCtx::new();
+    let worker_ctx = ctx.clone();
+    let outputs = vec![(first.clone(), join(&dir, "out/first.png")), (second, second_out.clone())];
+    let worker = std::thread::spawn(move || {
+        let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+        super::batch_run::process_batch_outputs(72.0, outputs, "png", SaveOpts::default(), &policy, &worker_ctx, &|_, path| {
+            if path.ends_with("first.png") {
+                assert!(worker_ctx.request_batch_interrupt());
+                return Err(EngineError::Other("boom".into()));
+            }
+            Ok(false)
+        })
+    });
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while !ctx.batch_waiting_for_decision() && std::time::Instant::now() < deadline {
+        std::thread::yield_now();
+    }
+    assert!(ctx.decide_batch_interrupt(true));
+    let result = worker.join().unwrap().unwrap();
+    assert_eq!(result["errors"], json!([{"file": first, "error": "boom"}]), "{result}");
+    assert_eq!(result["files"], json!([second_out]), "{result}");
+    assert!(result.get("skipped").is_none(), "{result}");
+}
+
+/// Once the last input is handled, Esc has nothing to interrupt and is refused, so the desktop
+/// never waits for a question that will not come.
+#[test]
+fn batch_refuses_esc_after_its_last_input() {
+    let dir = tmp("batch-late-esc");
+    let input = png(&dir, "source.png", 8, 6, "#ff0000");
+    let ctx = crate::jobs::JobCtx::new();
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+    let result =
+        super::batch_run::process_batch_outputs(72.0, vec![(input, join(&dir, "out/source.png"))], "png", SaveOpts::default(), &policy, &ctx, &|_, _| {
+            Ok(false)
+        })
+        .unwrap();
+    assert_eq!(result["errors"], json!([]), "{result}");
+    assert!(!ctx.request_batch_interrupt());
+}
+
 #[cfg(not(target_arch = "wasm32"))]
 #[test]
 fn batch_interruption_continues_with_the_original_next_output() {
diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index 6a792b7b0e..34ac2c12a9 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -116,6 +116,8 @@ enum BatchInterrupt {
     Continue,
     Stop,
     Saving,
+    /// Every input has been handled; Esc is no longer accepted.
+    Closed,
 }
 
 const CANCEL_REQUESTED: u8 = 1;
@@ -247,6 +249,13 @@ impl JobCtx {
         Ok(())
     }
 
+    /// The worker has passed its last checkpoint. A pending request is dropped (nothing is left to
+    /// interrupt) and later requests return false.
+    pub(crate) fn batch_close_interrupts(&self) {
+        *self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) = BatchInterrupt::Closed;
+        self.shared.batch_decision.notify_all();
+    }
+
     /// A completed write allows Esc on the next input.
     pub(crate) fn batch_after_write(&self) {
         let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index e9f073db1e..1c945f696c 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -250,7 +250,7 @@ The shape is pinned by a test in `crates/automation/src/rpc.rs` (#3684).
 
 ### Background jobs (#210)
 
-Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged; a folder Batch can already have written earlier output files. A cancelled Batch has `state: "cancelled"` with its partial `result` in `jobs.list`; a waiting control request receives `{"ok":false,"error":"cancelled","result":…}`. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
+Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged; a folder Batch can already have written earlier output files. A cancelled Batch has `state: "cancelled"` with its partial `result` in `jobs.list`; a waiting control request receives `{"ok":false,"error":"cancelled","result":…}`, and an MCP call through the app bridge gets the error `cancelled; partial result: {…}`. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
 
 ## Preferences
 

From 1b7b56d9f5f6a0893cf20306a6ebb2bd8cf061b5 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 14:51:01 +0100
Subject: [PATCH 100/109] GPU canvas: the open documents share one texture
 budget

The canvas budget was each document's: N open documents could hold N
times it (#5332 review). It is now all of them together. The app
publishes the documents on screen (the arranged tiles or the main
canvas's, plus open document windows) with each one's texture set size;
those split the budget max-min fairly, and fits_canvas, canvas_fit and
the viewport page limit use a document's share, so a document over it is
drawn from pages. A document alone on screen still has the whole budget.

Documents no window shows keep their textures while there is room, so
going back to a tab is free, and are freed first, least recently shown
first, when a shown document's texture set or pages need the room.
Previews and adjustment proxies are never freed for another document.
The split changes only when the shown set or a size changes, not with
focus, so switching between shown documents moves no texture.
---
 .../src/canvas/background_redraw/tests.rs     |  57 +++++
 crates/ui-egui/src/canvas/gpu_canvas.rs       |  43 +++-
 .../src/canvas/gpu_canvas/doc_textures.rs     |  10 +
 crates/ui-egui/src/canvas/gpu_canvas/pages.rs |   5 +-
 .../src/canvas/gpu_canvas/residency.rs        | 209 ++++++++++++++++++
 .../src/canvas/gpu_canvas/resources.rs        |   5 +-
 crates/ui-egui/src/canvas/tabs.rs             |  21 ++
 crates/ui-egui/src/canvas/viewport_pages.rs   |   5 +-
 8 files changed, 340 insertions(+), 15 deletions(-)
 create mode 100644 crates/ui-egui/src/canvas/gpu_canvas/residency.rs

diff --git a/crates/ui-egui/src/canvas/background_redraw/tests.rs b/crates/ui-egui/src/canvas/background_redraw/tests.rs
index a669b18a38..ce47c0c003 100644
--- a/crates/ui-egui/src/canvas/background_redraw/tests.rs
+++ b/crates/ui-egui/src/canvas/background_redraw/tests.rs
@@ -699,6 +699,63 @@ fn a_canvas_over_the_texture_budget_draws_its_viewport_pages_on_the_gpu() {
     assert!(gpu.pages(key).0.is_empty());
 }
 
+/// #5332 review: the open documents share one texture budget rather than each having all of
+/// it. A document alone on screen keeps the whole budget; one in a background tab gives its
+/// textures up when the shown one needs the room; and documents shown side by side split it,
+/// a document over its share drawing from viewport pages.
+#[test]
+fn open_documents_share_one_texture_budget_with_the_shown_ones_first() {
+    let _gpu = photocraft_testkit::gpu_lock();
+    let Some(mut g) = gpu_app() else { return };
+    let gpu = g.harness.state().gpu.clone().expect("gpu canvas");
+    let new = |g: &mut Gpu| {
+        g.harness.state_mut().run("file.new", json!({"width": 3000, "height": 2000, "background": "#336699"})).expect("new");
+        g.harness.run_steps(3);
+        assert!(on_gpu_canvas(g), "{:?}", render_path_of(g));
+        g.harness.state().session.active().expect("document").doc.clone()
+    };
+    let a = new(&mut g);
+    let (set, _) = gpu.canvas_fit(&a).expect("fit");
+    // Room for one texture set and a half: a document alone on screen has all of it.
+    let budget = set + set / 2;
+    gpu.set_canvas_budget(budget);
+    assert_eq!(gpu.canvas_fit(&a), Some((set, budget)), "alone, the whole budget");
+    assert!(gpu.texture_info(a.id.0).is_some());
+    // A second tab: the shown document's texture set takes the room of the background one's.
+    let b = new(&mut g);
+    assert_eq!(gpu.canvas_fit(&b), Some((set, budget)));
+    assert!(gpu.texture_info(b.id.0).is_some());
+    assert!(gpu.texture_info(a.id.0).is_none(), "the background document's textures are freed");
+    // Back to the first tab: it gets its texture set back and the other gives its up.
+    g.harness.state_mut().session.set_active(0);
+    g.harness.run_steps(3);
+    assert!(on_gpu_canvas(&g), "{:?}", render_path_of(&g));
+    assert!(gpu.texture_info(a.id.0).is_some());
+    assert!(gpu.texture_info(b.id.0).is_none());
+    // Side by side, they split the budget: neither set fits its half, so both draw from pages.
+    g.harness.state_mut().ui.view.arrange = "twoUpVertical".into();
+    g.harness.run_steps(3);
+    assert_eq!(gpu.canvas_fit(&a), Some((set, budget / 2)));
+    assert_eq!(gpu.canvas_fit(&b), Some((set, budget - budget / 2)));
+    settle_pages(&mut g);
+    assert!(on_gpu_canvas(&g), "{:?}", render_path_of(&g));
+    let streams = &g.harness.state().streams;
+    assert!(streams.contains_key(&a.id) && streams.contains_key(&b.id), "both on pages");
+    assert!(gpu.texture_info(a.id.0).is_none() && gpu.texture_info(b.id.0).is_none());
+    // Switching between them re-splits nothing: no page set is dropped.
+    let held = gpu.pages(crate::canvas::viewport_pages::stream_key(a.id.0)).0;
+    g.harness.state_mut().session.set_active(1);
+    g.harness.run_steps(3);
+    assert_eq!(gpu.canvas_fit(&a), Some((set, budget / 2)));
+    assert_eq!(gpu.pages(crate::canvas::viewport_pages::stream_key(a.id.0)).0, held, "no churn on a switch");
+    // Back to tabs: the shown document has the whole budget, and its texture set, again.
+    g.harness.state_mut().ui.view.arrange = "tabs".into();
+    g.harness.run_steps(3);
+    assert_eq!(gpu.canvas_fit(&b), Some((set, budget)));
+    assert!(on_gpu_canvas(&g), "{:?}", render_path_of(&g));
+    assert!(gpu.texture_info(b.id.0).is_some());
+}
+
 #[test]
 fn a_flipped_view_records_why_it_draws_on_the_cpu() {
     let _gpu = photocraft_testkit::gpu_lock();
diff --git a/crates/ui-egui/src/canvas/gpu_canvas.rs b/crates/ui-egui/src/canvas/gpu_canvas.rs
index 19a3b55846..ef9435f346 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas.rs
@@ -42,6 +42,7 @@ mod callback;
 mod doc_textures;
 mod pages;
 mod perf;
+mod residency;
 mod resources;
 mod setup;
 mod shaders;
@@ -349,24 +350,43 @@ impl GpuCanvas {
         r.callback_resources.get::<Resources>()?.compositor_budget
     }
 
-    /// Set the GPU bytes one document's display texture set may take (see [`canvas_budget`]).
+    /// Set the GPU bytes the open documents' display textures may take together (see
+    /// [`canvas_budget`] and [`GpuCanvas::show_documents`]).
     pub fn set_canvas_budget(&self, bytes: u64) {
         self.canvas_budget.store(bytes, Ordering::Relaxed);
     }
 
-    /// Whether `doc`'s display textures fit [`canvas_budget`]; when they don't, nothing is
-    /// created for it and it is drawn on the CPU canvas.
+    /// Whether `doc`'s display textures fit its share of [`canvas_budget`]; when they don't,
+    /// nothing is created for it and it is drawn from viewport pages or on the CPU canvas.
     pub fn fits_canvas(&self, doc: &photocraft_doc::Document) -> bool {
         self.canvas_fit(doc).is_some_and(|(bytes, budget)| bytes <= budget)
     }
 
-    /// The bytes `doc`'s display textures would take and [`canvas_budget`] (`None` without a GPU
-    /// canvas): the numbers of a [`CpuReason::CanvasTooLarge`].
-    pub fn canvas_fit(&self, doc: &photocraft_doc::Document) -> Option<(u64, u64)> {
+    /// The bytes `doc`'s whole-document texture set would take.
+    pub fn canvas_bytes(&self, doc: &photocraft_doc::Document) -> u64 {
         let size = [doc.size.width, doc.size.height];
-        let bytes = canvas_texture_bytes(size, self.tile, texel_bytes(self.format_for(doc.depth, size)));
+        canvas_texture_bytes(size, self.tile, texel_bytes(self.format_for(doc.depth, size)))
+    }
+
+    /// The bytes `doc`'s display textures would take and its share of [`canvas_budget`] (`None`
+    /// without a GPU canvas): the numbers of a [`CpuReason::CanvasTooLarge`]. Alone on screen a
+    /// document has the whole budget; see [`GpuCanvas::show_documents`].
+    pub fn canvas_fit(&self, doc: &photocraft_doc::Document) -> Option<(u64, u64)> {
+        let bytes = self.canvas_bytes(doc);
         let r = self.rs.renderer.read();
-        r.callback_resources.get::<Resources>().map(|res| (bytes, res.canvas_budget.load(Ordering::Relaxed)))
+        r.callback_resources.get::<Resources>().map(|res| (bytes, res.residency.share(res.canvas_budget.load(Ordering::Relaxed), doc.id.0, bytes)))
+    }
+
+    /// The documents the app's windows show now, with [`GpuCanvas::canvas_bytes`] of each: they
+    /// split [`canvas_budget`] (see [`residency`]), and the textures of documents not among them
+    /// are freed first when a shown one needs the room. Cheap when nothing changed.
+    pub fn show_documents(&self, shown: &[(u64, u64)]) {
+        if self.rs.renderer.read().callback_resources.get::<Resources>().is_none_or(|res| res.residency.shows(shown)) {
+            return;
+        }
+        if let Some(res) = self.rs.renderer.write().callback_resources.get_mut::<Resources>() {
+            res.residency.publish(shown);
+        }
     }
 
     /// Act as if the driver couldn't build the compositor's pipelines (the DX12 FXC X3507 case,
@@ -513,7 +533,7 @@ impl GpuCanvas {
         let mut renderer = self.rs.renderer.write();
         let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return };
         if res.docs.get(&doc).is_none_or(|d| d.size != size || d.format != format) {
-            let Some(tex) = DocTextures::new(device, res, size, self.tile, format) else {
+            let Some(tex) = DocTextures::new_for(device, res, doc, size, self.tile, format) else {
                 res.docs.remove(&doc);
                 return;
             };
@@ -646,7 +666,7 @@ impl GpuCanvas {
             }
         }
         if fresh {
-            let Some(tex) = DocTextures::new(device, res, size, self.tile, format) else {
+            let Some(tex) = DocTextures::new_for(device, res, key, size, self.tile, format) else {
                 res.docs.remove(&key);
                 res.compositor = Some(comp);
                 return Err(photocraft_gpu::Unsupported(OVER_CANVAS_BUDGET.into()));
@@ -861,7 +881,7 @@ impl GpuCanvas {
         let mut renderer = self.rs.renderer.write();
         let res = renderer.callback_resources.get_mut::<Resources>()?;
         if res.docs.get(&key).is_none_or(|d| d.size != size || d.format != format) {
-            let Some(tex) = DocTextures::new(&self.rs.device, res, size, self.tile, format) else {
+            let Some(tex) = DocTextures::new_for(&self.rs.device, res, key, size, self.tile, format) else {
                 res.docs.remove(&key);
                 return None;
             };
@@ -886,6 +906,7 @@ impl GpuCanvas {
         // LUTs and identity-transform signatures can outlive document textures. Prune both,
         // or a preserved-ID reopen can skip rebuilding a missing LUT.
         res.luts.retain(|k, _| live.contains(&k.0));
+        res.residency.retain(|d| live.contains(&d));
         res.display_lut_signatures.retain(|k, _| live.contains(&k.0));
     }
 
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs b/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
index e21efd41ca..e1c2389bfb 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/doc_textures.rs
@@ -81,6 +81,16 @@ impl DocTextures {
         Some(set)
     }
 
+    /// [`DocTextures::new`] for key `key`, first freeing the textures of documents no window
+    /// shows when the open documents' together wouldn't fit the canvas budget.
+    pub(super) fn new_for(device: &wgpu::Device, res: &mut Resources, key: u64, size: [u32; 2], tile: u32, format: wgpu::TextureFormat) -> Option<Self> {
+        let bytes = canvas_texture_bytes(size, tile, texel_bytes(format));
+        if bytes <= res.canvas_budget.load(Ordering::Relaxed) {
+            res.make_room(key, bytes);
+        }
+        Self::new(device, res, size, tile, format)
+    }
+
     fn create(device: &wgpu::Device, res: &Resources, size: [u32; 2], tile: u32, format: wgpu::TextureFormat) -> Self {
         let mut tiles = Vec::new();
         for ty in (0..size[1]).step_by(tile as usize) {
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/pages.rs b/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
index 05ff59ee40..bc62505d7e 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/pages.rs
@@ -108,6 +108,8 @@ impl GpuCanvas {
         if held.saturating_add(bytes) > budget {
             return false;
         }
+        // Room among the other documents: those no window shows give theirs up first.
+        res.make_room(key, held + bytes);
         let rect = [x, y, dw, dh];
         // A page the GPU refuses (out of memory) fails alone: it falls back to the CPU canvas
         // instead of the uncaptured error disabling the GPU canvas for the session.
@@ -189,7 +191,8 @@ impl GpuCanvas {
         (d.tiles.iter().filter_map(|t| t.page.map(|(id, _)| id)).collect(), d.page_bytes())
     }
 
-    /// The per-document display texture budget ([`super::canvas_budget`]) pages are held to.
+    /// The display texture budget all documents share ([`super::canvas_budget`]); a document's
+    /// pages are held to its share ([`GpuCanvas::canvas_fit`]).
     pub fn canvas_budget(&self) -> u64 {
         self.canvas_budget.load(Ordering::Relaxed)
     }
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/residency.rs b/crates/ui-egui/src/canvas/gpu_canvas/residency.rs
new file mode 100644
index 0000000000..df681a000b
--- /dev/null
+++ b/crates/ui-egui/src/canvas/gpu_canvas/residency.rs
@@ -0,0 +1,209 @@
+//! One display-texture budget ([`super::canvas_budget`]) for every open document, rather than
+//! the whole budget for each (N documents could hold N times it, #5332 review).
+//!
+//! The app publishes the documents its windows show and what each one's whole-document texture
+//! set needs ([`super::GpuCanvas::show_documents`]). Those split the budget max-min fairly: a
+//! document that fits its share keeps its texture set, a larger one is drawn from viewport pages
+//! within it, and a document alone on screen still has the whole budget. The split changes only
+//! when the shown documents (or their sizes) do, never with focus, so switching between windows
+//! moves nothing. Documents no window shows have no share: they keep their textures while there
+//! is room (switching back to a tab is free) and are the first freed, least recently shown
+//! first, when a shown document needs the room.
+
+use std::collections::HashMap;
+use std::sync::atomic::Ordering;
+
+use super::resources::{DocTextures, Resources};
+use super::texels::texel_bytes;
+
+/// Keys tagged above this bit are previews (filter preview, adjustment proxies, gradients,
+/// thumbnails): never evicted for another document.
+const TAG_BITS: u64 = !((1u64 << 58) - 1);
+/// The tag of a document's viewport pages (`viewport_pages::stream_key`).
+const PAGES_BIT: u64 = 1u64 << 57;
+
+impl DocTextures {
+    /// GPU bytes of every texture (all mip levels) in this set or page set.
+    pub(super) fn bytes(&self) -> u64 {
+        let bpp = texel_bytes(self.format);
+        let level = |w: u32, h: u32, l: u32| u64::from((w >> l).max(1)) * u64::from((h >> l).max(1)) * bpp;
+        self.tiles.iter().map(|t| (0..t.texture.mip_level_count()).map(|l| level(t.texture.width(), t.texture.height(), l)).sum::<u64>()).sum()
+    }
+}
+
+impl Resources {
+    /// Free the textures of documents no window shows ([`Residency::victims`]) so that `key`
+    /// can hold `bytes` within the canvas budget.
+    pub(super) fn make_room(&mut self, key: u64, bytes: u64) {
+        let budget = self.canvas_budget.load(Ordering::Relaxed);
+        let held: Vec<(u64, u64)> = self.docs.iter().map(|(k, d)| (*k, d.bytes())).collect();
+        for k in self.residency.victims(&held, key, bytes, budget) {
+            log::debug!("freeing the display textures of background key {k:#x} for {key:#x}");
+            self.docs.remove(&k);
+        }
+    }
+}
+
+/// Document `doc`'s allocation when documents needing `needs` bytes split `budget` max-min
+/// fairly (`doc` indexes `needs`): those needing less than an equal share take what they need,
+/// the rest split what is left; the leftover, if any, is `doc`'s too.
+pub(super) fn fair_share(budget: u64, needs: &[u64], doc: usize) -> u64 {
+    let mut order: Vec<usize> = (0..needs.len()).collect();
+    order.sort_by_key(|&i| needs[i]);
+    let mut left = budget;
+    let mut others = 0u64;
+    for (n, &i) in order.iter().enumerate() {
+        let take = needs[i].min(left / (order.len() - n) as u64);
+        left -= take;
+        if i != doc {
+            others += take;
+        }
+    }
+    budget - others
+}
+
+/// The documents on screen and when each was last shown.
+#[derive(Default)]
+pub(super) struct Residency {
+    /// Shown documents: (document id, bytes of its whole texture set).
+    shown: Vec<(u64, u64)>,
+    /// When each document was last among the shown (a counter of changes).
+    seen: HashMap<u64, u64>,
+    tick: u64,
+}
+
+impl Residency {
+    /// Record the shown documents. False when nothing changed.
+    pub(super) fn publish(&mut self, shown: &[(u64, u64)]) -> bool {
+        if self.shown == shown {
+            return false;
+        }
+        self.tick += 1;
+        for (id, _) in shown {
+            self.seen.insert(*id, self.tick);
+        }
+        self.shown = shown.to_vec();
+        true
+    }
+
+    /// The share of `budget` document `id` (its texture set `need` bytes) may hold: the whole
+    /// budget when nothing else is shown.
+    pub(super) fn share(&self, budget: u64, id: u64, need: u64) -> u64 {
+        let mut needs: Vec<u64> = self.shown.iter().filter(|(d, _)| *d != id).map(|(_, n)| *n).collect();
+        needs.push(need);
+        fair_share(budget, &needs, needs.len() - 1)
+    }
+
+    /// Which held keys (`held`: key and bytes) to free, in order, so that `key` can hold
+    /// `bytes` within `budget`: the texture sets and pages of documents no window shows, least
+    /// recently shown first. Never a shown document's, nor `key`'s own document's, nor a preview
+    /// or a key of a document never shown (an adjustment proxy). It may not free enough: what
+    /// a shown document takes is bounded by its share instead.
+    pub(super) fn victims(&self, held: &[(u64, u64)], key: u64, bytes: u64, budget: u64) -> Vec<u64> {
+        let owner = |k: u64| (k & TAG_BITS == 0).then_some(k & !PAGES_BIT);
+        let mut total = held.iter().filter(|(k, _)| *k != key).map(|(_, b)| *b).fold(bytes, u64::saturating_add);
+        if total <= budget {
+            return Vec::new();
+        }
+        let mine = owner(key);
+        let mut cold: Vec<(u64, u64, u64)> = held
+            .iter()
+            .filter_map(|&(k, b)| {
+                let d = owner(k)?;
+                let at = *self.seen.get(&d)?;
+                (Some(d) != mine && !self.shown.iter().any(|(s, _)| *s == d)).then_some((at, k, b))
+            })
+            .collect();
+        cold.sort_unstable();
+        let mut out = Vec::new();
+        for (_, k, b) in cold {
+            if total <= budget {
+                break;
+            }
+            total -= b;
+            out.push(k);
+        }
+        out
+    }
+
+    /// Whether `shown` is what was published last.
+    pub(super) fn shows(&self, shown: &[(u64, u64)]) -> bool {
+        self.shown == shown
+    }
+
+    /// Forget closed documents.
+    pub(super) fn retain(&mut self, live: impl Fn(u64) -> bool) {
+        self.seen.retain(|d, _| live(*d));
+        self.shown.retain(|(d, _)| live(*d));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const GB: u64 = 1 << 30;
+
+    #[test]
+    fn one_document_has_the_whole_budget() {
+        let r = Residency::default();
+        assert_eq!(r.share(4 * GB, 1, 9 * GB), 4 * GB);
+        let mut r = Residency::default();
+        r.publish(&[(1, 9 * GB)]);
+        assert_eq!(r.share(4 * GB, 1, 9 * GB), 4 * GB, "shown alone");
+        assert_eq!(r.share(4 * GB, 1, GB), 4 * GB);
+    }
+
+    #[test]
+    fn shown_documents_split_the_budget_max_min_fairly() {
+        let mut r = Residency::default();
+        // A small document takes what it needs; the large one the rest.
+        r.publish(&[(1, GB), (2, 9 * GB)]);
+        assert_eq!(r.share(4 * GB, 1, GB), GB);
+        assert_eq!(r.share(4 * GB, 2, 9 * GB), 3 * GB);
+        // What the others leave is the asking document's too.
+        r.publish(&[(1, GB), (2, 2 * GB)]);
+        assert_eq!(r.share(4 * GB, 2, 2 * GB), 3 * GB, "the leftover is its own too");
+        // Two large ones split it evenly, whichever has focus: no churn switching windows.
+        r.publish(&[(1, 3 * GB), (2, 3 * GB)]);
+        assert_eq!(r.share(4 * GB, 1, 3 * GB), 2 * GB);
+        assert_eq!(r.share(4 * GB, 2, 3 * GB), 2 * GB);
+        // Three, one of them small.
+        r.publish(&[(1, 3 * GB), (2, 3 * GB), (3, GB / 2)]);
+        assert_eq!(r.share(4 * GB, 1, 3 * GB), 7 * GB / 4);
+        assert_eq!(r.share(4 * GB, 3, GB / 2), GB / 2, "needs only half a GB");
+        // Everything fits: each share covers its need, together within the budget.
+        r.publish(&[(1, GB), (2, GB)]);
+        assert!(r.share(4 * GB, 1, GB) >= GB && r.share(4 * GB, 2, GB) >= GB);
+        // A document no window shows (a refresh of a background tab) is priced as one more.
+        assert_eq!(r.share(4 * GB, 7, 4 * GB), 2 * GB);
+    }
+
+    #[test]
+    fn republishing_the_same_documents_changes_nothing() {
+        let mut r = Residency::default();
+        assert!(r.publish(&[(1, GB)]));
+        assert!(!r.publish(&[(1, GB)]));
+        assert!(r.publish(&[(1, 2 * GB)]), "the document was resized");
+    }
+
+    #[test]
+    fn background_documents_are_freed_least_recently_shown_first() {
+        let mut r = Residency::default();
+        // Tabs 1, 2, 3 shown in turn, then 4.
+        for d in 1..=4 {
+            r.publish(&[(d, GB)]);
+        }
+        let pages = |d: u64| d ^ PAGES_BIT;
+        let held = [(1, GB), (pages(2), GB / 2), (2, GB / 2), (3, GB), (1 << 61 | 3, GB), (99, GB)];
+        // Room enough: nothing goes.
+        assert!(r.victims(&held, 4, GB, 16 * GB).is_empty());
+        // 4 needs 2 GB within 6 GB (5 held): tab 1 goes first, then tab 2's pages and set.
+        assert_eq!(r.victims(&held, 4, 2 * GB, 6 * GB), vec![1]);
+        assert_eq!(r.victims(&held, 4, 3 * GB, 6 * GB), vec![1, 2, pages(2)]);
+        // Never a shown document's, a preview's or an unknown key's, even when that isn't enough.
+        assert_eq!(r.victims(&held, 4, 10 * GB, 6 * GB), vec![1, 2, pages(2), 3]);
+        // Nor the document's own: its pages make room by evicting the other tabs.
+        assert_eq!(r.victims(&held, pages(3), GB, 4 * GB), vec![1, 2, pages(2)]);
+    }
+}
diff --git a/crates/ui-egui/src/canvas/gpu_canvas/resources.rs b/crates/ui-egui/src/canvas/gpu_canvas/resources.rs
index ce8f8b0881..d9990f0920 100644
--- a/crates/ui-egui/src/canvas/gpu_canvas/resources.rs
+++ b/crates/ui-egui/src/canvas/gpu_canvas/resources.rs
@@ -36,8 +36,10 @@ pub(super) struct Resources {
     pub(super) layer_fit: Option<LayerFit>,
     pub(super) compositor_cache_budget: Option<u64>,
     pub(super) compositor_focus: Option<photocraft_geom::Rect>,
-    /// GPU bytes one document's display texture set may take (see [`canvas_budget`]).
+    /// GPU bytes the documents' display textures may take together (see [`canvas_budget`]).
     pub(super) canvas_budget: std::sync::Arc<std::sync::atomic::AtomicU64>,
+    /// How that budget is split between the open documents (see [`super::residency`]).
+    pub(super) residency: super::residency::Residency,
     pub(super) encode_bgl: wgpu::BindGroupLayout,
     encode_pipeline: wgpu::RenderPipeline,
     pub(super) lut_bgl: wgpu::BindGroupLayout,
@@ -369,6 +371,7 @@ impl Resources {
             compositor_cache_budget: None,
             compositor_focus: None,
             canvas_budget: std::sync::Arc::new(std::sync::atomic::AtomicU64::new(canvas_budget(physical_memory(), None))),
+            residency: Default::default(),
             encode_bgl,
             encode_pipeline,
         }
diff --git a/crates/ui-egui/src/canvas/tabs.rs b/crates/ui-egui/src/canvas/tabs.rs
index 2ab777b532..3753ad3d2b 100644
--- a/crates/ui-egui/src/canvas/tabs.rs
+++ b/crates/ui-egui/src/canvas/tabs.rs
@@ -29,10 +29,29 @@ pub(crate) fn arranged_cells(app: &PhotocraftApp, rect: Rect) -> Option<Vec<(usi
     Some(documents[start..].iter().copied().zip(cells).collect())
 }
 
+/// Tell the GPU canvas which documents are on screen (the arranged tiles or the main canvas's,
+/// plus those of open document windows): they split the display texture budget, and the
+/// textures of the others are freed first. Only a change of that set (or a document's size)
+/// re-splits it, so switching between shown documents or windows moves no texture.
+pub(crate) fn publish_shown(app: &PhotocraftApp) {
+    let Some(gpu) = &app.gpu else { return };
+    let docs = app.session.documents();
+    let mut shown: Vec<usize> = match arranged_cells(app, app.last_canvas_rect) {
+        Some(cells) => cells.into_iter().map(|(d, _)| d).collect(),
+        None => main_canvas_document(app).into_iter().collect(),
+    };
+    shown.extend(app.ui.windows.iter().filter(|w| w.open).map(|w| w.document));
+    let mut shown: Vec<(u64, u64)> = shown.into_iter().filter_map(|d| docs.get(d)).map(|st| (st.doc.id.0, gpu.canvas_bytes(&st.doc))).collect();
+    shown.sort_unstable();
+    shown.dedup();
+    gpu.show_documents(&shown);
+}
+
 fn documents(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
     app.drop_canvas_rect = None;
     app.tab_strip = None;
     retain_gpu_documents(app);
+    publish_shown(app);
     crate::transform_tool::track_steps(app, ui.ctx());
     crate::cas_transform::tick(app, ui.ctx());
     crate::symmetry_ui::track(app, ui.ctx());
@@ -66,6 +85,8 @@ fn documents(app: &mut PhotocraftApp, ui: &mut egui::Ui) {
         app.tab_strip = Some(tabs(app, ui));
         ui.spacing_mut().item_spacing.y = spacing;
         drop_slot_line(app, ui);
+        // A tab click switches documents before any canvas is drawn this frame.
+        publish_shown(app);
     }
     if let Some(job) = app.jobs.focus.or_else(|| (n == 0).then(|| app.jobs.opens.last().map(|o| o.job)).flatten()) {
         crate::jobs_ui::open_card(app, ui, job);
diff --git a/crates/ui-egui/src/canvas/viewport_pages.rs b/crates/ui-egui/src/canvas/viewport_pages.rs
index e05455d51b..07933ede30 100644
--- a/crates/ui-egui/src/canvas/viewport_pages.rs
+++ b/crates/ui-egui/src/canvas/viewport_pages.rs
@@ -628,8 +628,9 @@ pub(super) fn show(app: &mut PhotocraftApp, ctx: &egui::Context, idx: usize, xf:
         return false;
     }
     let key = stream_key(id.0);
-    // Half the per-document canvas budget: the rest is headroom for what the compositor needs.
-    let limit = gpu.canvas_budget() / 2;
+    // Half the document's share of the canvas budget: the rest is headroom for what the
+    // compositor needs.
+    let limit = gpu.canvas_fit(&doc).map_or(0, |(_, share)| share) / 2;
     let page_bytes = gpu.page_texture_bytes(doc.depth, size, PAGE_SIDE + 2, PAGE_SIDE + 2).max(1);
     let max_pages = usize::try_from(limit / page_bytes).unwrap_or(usize::MAX);
     // No room for a single page: the CPU canvas draws the document, as main does for every

From 43f415bcf051af07a7b9b71acd50dbaae5429aa8 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 15:07:24 +0100
Subject: [PATCH 101/109] Type tool tests: let the options bar harness settle
 in up to 16 passes

options_font_family_preserves_peer_faces_and_batches_layer_flags failed
under a loaded parallel run at its first `h.run()` after opening the
family field:

  Harness::run exceeded max_steps (8). It would have settled after 10
  steps.

The test has no timeout of its own. The limit it hits is the egui_kittest
`max_steps` cap of the shared `controls()` harness. The font popup fills
in over several passes, and egui 0.37's `widget_style` requests one more
repaint for each widget it has not seen yet, so `run` settles only after
the last batch of the font list has arrived. Alone that takes six passes,
but under load the list arrives in more batches and it took ten.

Raise the cap from 8 to 16, well above the ten seen. It stays bounded: a
UI that keeps requesting repaints still fails, because `run` errors on any
pass past the cap.
---
 crates/ui-egui/src/tools/type_tool/canvas_tests.rs | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/crates/ui-egui/src/tools/type_tool/canvas_tests.rs b/crates/ui-egui/src/tools/type_tool/canvas_tests.rs
index fbe0d88c7c..38baecc450 100644
--- a/crates/ui-egui/src/tools/type_tool/canvas_tests.rs
+++ b/crates/ui-egui/src/tools/type_tool/canvas_tests.rs
@@ -1943,9 +1943,12 @@ mod multi_layer_formatting {
 
     fn controls(app: PhotocraftApp, properties: bool) -> Harness<'static, PhotocraftApp> {
         // The lazily populated font popup introduces widgets in successive passes. egui 0.37
-        // styles each new widget on its following pass; keep a bounded settle assertion while
-        // allowing those additional passes (the loaded menu requires six under parallel tests).
-        let mut h = Harness::builder().with_size(vec2(1100.0, 800.0)).with_max_steps(8).build_ui_state(
+        // styles each new widget on its following pass (`widget_style` requests a repaint for a
+        // widget it has not seen yet), so `run` settles only after the last batch of the font
+        // list has arrived. The loaded menu takes six passes alone, but under a loaded parallel
+        // run the list arrives in more batches and it took ten. Allow 16 passes; a UI that never
+        // settles still fails, because `run` errors on any pass past the cap.
+        let mut h = Harness::builder().with_size(vec2(1100.0, 800.0)).with_max_steps(16).build_ui_state(
             move |ui, app| {
                 if ui.ctx().fonts(|f| f.families().contains(&egui::FontFamily::Name("medium".into()))) {
                     if properties {

From 62c89c87e7bd9a3d5135dc9e13f5de37295e5afe Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 15:30:25 +0100
Subject: [PATCH 102/109] Tests: the Opened Files failed-write case blocks the
 write with a folder

A path under a regular file can't be resolved on Linux (ENOTDIR), so Batch
refused the whole run before writing and the test failed there. A folder
taking the result's name resolves on every platform and fails the write.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/file_cmds/tests.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 7c49ed2151..2cdf347aeb 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -543,11 +543,11 @@ fn batch_open_source_save_step_leaves_an_unwritten_document_changed() {
     let result = session.execute("file.automate.batch", json!({"source": "open", "steps": steps})).unwrap();
     assert_eq!(result["errors"], json!([]), "{result}");
     assert!(session.documents()[0].is_dirty(), "a document Batch did not write stays changed");
-    // A destination that can't be written: the write fails.
+    // A destination that can't be written: the result's name is taken by a folder, so the path
+    // resolves on every platform and the write itself fails.
     let dir = tmp("batch-open-save-fails");
-    let blocker = join(&dir, "not-a-folder");
-    std::fs::write(&blocker, b"file").unwrap();
-    let result = session.execute("file.automate.batch", json!({"source": "open", "steps": steps, "output": blocker, "format": "png"})).unwrap();
+    std::fs::create_dir_all(join(&dir, "First.png")).unwrap();
+    let result = session.execute("file.automate.batch", json!({"source": "open", "steps": steps, "output": dir, "format": "png"})).unwrap();
     assert_eq!(result["errors"].as_array().map(Vec::len), Some(1), "{result}");
     assert!(session.documents()[0].is_dirty(), "a failed write leaves the document changed");
 }

From 26d151d061ded4150d2f7200091228a375742c42 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 16:09:07 +0100
Subject: [PATCH 103/109] Jobs: a save past its commit point can't be reported
 as cancelled

jobs.cancel, cancel_all_jobs and closing a document (cancel_jobs_on) cancelled
any running job, so they could report a save as cancelled while its worker
went on to replace the file. The point of no return was tracked only by the
desktop shell's own Cancel/Esc path.

The commit point now lives in the engine's JobCtx: commit() and a cancel race
on one compare-and-swap, so exactly one wins.
- Cancelled before commit: commit() fails, the save writes nothing and the
  job ends Cancelled.
- Committed: every cancel path leaves the job running and says so
  (Session::try_cancel_job -> CancelRefused::Committing; cancel_all_jobs and
  cancel_jobs_on return a CancelReport). The job then reports its real
  outcome, applied even if its document was closed meanwhile.
- jobs.cancel (engine and desktop control) replies {cancelled: n} as before,
  plus notCancelled: [{job, reason: "committing"}] for a save left running.
  This is not an error: the job is fine and will report how it ended.
  Single-job print refusals are unchanged.
- The shell's SaveCtl::commit and Cancel/Esc use the engine gate, so the
  status bar, control and scripting agree.

Tests: cancel before commit (target untouched, Cancelled), cancel after
commit (refused, Done, file written), cancel_all and document close with
mixed committed/open jobs, a commit/cancel race, and desktop jobs.cancel
before and during the write with real files.
---
 crates/engine/src/jobs.rs              | 161 ++++++++++++++++----
 crates/engine/src/jobs/tests.rs        | 201 +++++++++++++++++++++++++
 crates/ui-egui/src/control/dispatch.rs |  22 ++-
 crates/ui-egui/src/jobs_ui.rs          |  48 +++---
 crates/ui-egui/src/jobs_ui/tests.rs    |  89 +++++++++++
 docs/control-protocol.md               |   4 +-
 6 files changed, 462 insertions(+), 63 deletions(-)

diff --git a/crates/engine/src/jobs.rs b/crates/engine/src/jobs.rs
index ae1b880a64..fa5f98ce6e 100644
--- a/crates/engine/src/jobs.rs
+++ b/crates/engine/src/jobs.rs
@@ -14,12 +14,17 @@
 //!   On wasm `start` runs inline (same API, written once).
 //! - [`Session::cancel_job`] sets the flag; the algorithms check it per tile, row band or
 //!   iteration, and the result is discarded. The document is never touched by a worker.
+//! - A job with an effect outside the session (a save replacing its file) calls
+//!   [`JobCtx::commit`] right before it. From then on it can't be cancelled: every cancel
+//!   path ([`Session::try_cancel_job`], [`Session::cancel_all_jobs`], closing its document,
+//!   `jobs.cancel`) leaves it running and says so ([`CancelRefused::Committing`]), so nothing
+//!   reports a job as cancelled after its effect has happened.
 //! - A panic in the worker becomes an error; the document is unchanged.
 //! - While a job runs on a document, commands that would edit that document are disabled with a
 //!   message naming the job (queries and document-independent commands still run).
 
 use std::any::Any;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, Ordering};
 use std::sync::{Arc, Mutex, PoisonError, Weak};
 
 use photocraft_doc::{DocId, Document, LayerId};
@@ -85,12 +90,22 @@ pub struct JobCtx {
 #[derive(Default)]
 struct Shared {
     cancel: AtomicBool,
+    /// [`OPEN`], [`COMMITTED`] or [`CANCELLED`]: one compare-and-swap decides between a cancel
+    /// and [`JobCtx::commit`], so exactly one of them wins.
+    phase: AtomicU8,
     /// `f32` bits of the progress fraction. Non-negative floats order like their bits, so
     /// `fetch_max` keeps progress monotonic even with several reporting threads.
     progress: AtomicU32,
     message: Mutex<String>,
 }
 
+/// Neither cancelled nor committed: a cancel stops the job.
+const OPEN: u8 = 0;
+/// Past [`JobCtx::commit`]: the job runs to the end and can no longer be cancelled.
+const COMMITTED: u8 = 1;
+/// Cancelled before it committed.
+const CANCELLED: u8 = 2;
+
 impl std::fmt::Debug for JobCtx {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("JobCtx").field("progress", &self.fraction()).field("cancelled", &self.cancelled()).finish()
@@ -121,9 +136,38 @@ impl JobCtx {
         self.shared.cancel.load(Ordering::Relaxed)
     }
 
-    /// Ask the job to stop (idempotent).
+    /// Ask the job to stop (idempotent). Does nothing once it has [committed](Self::commit).
     pub fn cancel(&self) {
-        self.shared.cancel.store(true, Ordering::Relaxed);
+        let _ = self.try_cancel();
+    }
+
+    /// Cancel unless the job has [committed](Self::commit): true if it is cancelled (now or
+    /// before), false if it is past its point of no return and will run to the end.
+    pub fn try_cancel(&self) -> bool {
+        match self.shared.phase.compare_exchange(OPEN, CANCELLED, Ordering::AcqRel, Ordering::Acquire) {
+            Ok(_) | Err(CANCELLED) => {
+                self.shared.cancel.store(true, Ordering::Release);
+                true
+            }
+            Err(_) => false,
+        }
+    }
+
+    /// The job's point of no return, for work with an effect outside the session (a save calls
+    /// it right before replacing the file). `Ok`: no cancel can stop the job any more; it must
+    /// run to the end, and its result is applied even if its document was closed meanwhile.
+    /// `Err(Cancelled)`: it was cancelled first, and nothing may be done.
+    pub fn commit(&self) -> Result<()> {
+        self.check()?;
+        match self.shared.phase.compare_exchange(OPEN, COMMITTED, Ordering::AcqRel, Ordering::Acquire) {
+            Ok(_) | Err(COMMITTED) => Ok(()),
+            Err(_) => Err(EngineError::Cancelled),
+        }
+    }
+
+    /// Has the job passed [`Self::commit`]?
+    pub fn committed(&self) -> bool {
+        self.shared.phase.load(Ordering::Acquire) == COMMITTED
     }
 
     /// `Err(Cancelled)` once cancelled, for `?` between stages.
@@ -151,6 +195,49 @@ impl JobCtx {
     }
 }
 
+/// Why [`Session::try_cancel_job`] left a job running.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CancelRefused {
+    /// No such job is running.
+    NotRunning,
+    /// A print belongs to the system print queue once it has started.
+    Printing,
+    /// Past its [commit](JobCtx::commit): it is writing its result (a save replacing its file)
+    /// and will report its real outcome when it ends.
+    Committing,
+}
+
+impl CancelRefused {
+    /// The scripting name (`jobs.cancel`'s `notCancelled[].reason`).
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::NotRunning => "notRunning",
+            Self::Printing => "printing",
+            Self::Committing => "committing",
+        }
+    }
+}
+
+/// What a cancel of several jobs did ([`Session::cancel_all_jobs`]).
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct CancelReport {
+    pub cancelled: Vec<JobId>,
+    /// The jobs left running, and why.
+    pub refused: Vec<(JobId, CancelRefused)>,
+}
+
+impl CancelReport {
+    /// The `jobs.cancel` reply: `{cancelled: n}`, with `notCancelled: [{job, reason}]` when a
+    /// job was left running.
+    pub fn to_json(&self) -> Value {
+        let mut v = json!({"cancelled": self.cancelled.len()});
+        if !self.refused.is_empty() {
+            v["notCancelled"] = self.refused.iter().map(|(id, why)| json!({"job": id.0, "reason": why.as_str()})).collect();
+        }
+        v
+    }
+}
+
 /// Final state of a job.
 #[derive(Clone, Debug, PartialEq)]
 pub enum JobOutcome {
@@ -1071,30 +1158,50 @@ impl Session {
     }
 
     /// Cancel job `id`: it stops at its next check, its result is discarded and the document
-    /// stays unchanged. The document is unlocked at once. False if no such job is running.
+    /// stays unchanged. The document is unlocked at once. False if no such job is running or it
+    /// can't be cancelled (see [`Self::try_cancel_job`]).
     pub fn cancel_job(&mut self, id: JobId) -> bool {
-        let Some(i) = self.jobs.running.iter().position(|r| r.id == id) else { return false };
+        self.try_cancel_job(id).is_ok()
+    }
+
+    /// [`Self::cancel_job`], saying why a job was not cancelled.
+    pub fn try_cancel_job(&mut self, id: JobId) -> std::result::Result<(), CancelRefused> {
+        let Some(i) = self.jobs.running.iter().position(|r| r.id == id) else { return Err(CancelRefused::NotRunning) };
         // A print worker can already have handed the job to the OS. Discarding its result
         // would falsely report cancellation; removal belongs to the system print queue.
         if matches!(self.jobs.running[i].command.as_str(), "file.print" | "file.printOneCopy") {
-            return false;
+            return Err(CancelRefused::Printing);
+        }
+        // Past its commit (a save replacing its file) the job runs to the end and reports its
+        // real outcome; calling it cancelled would be false.
+        if !self.jobs.running[i].ctx.try_cancel() {
+            return Err(CancelRefused::Committing);
         }
         let job = self.jobs.running.remove(i);
-        job.ctx.cancel();
         self.end_job(&job, JobOutcome::Cancelled);
         #[cfg(not(target_arch = "wasm32"))]
         if let Some(handle) = job.handle {
             self.jobs.draining.push(Draining { handle, doc: job.doc, release: false });
         }
-        true
+        Ok(())
     }
 
-    /// Cancel every running job (e.g. before quitting).
-    pub fn cancel_all_jobs(&mut self) {
+    /// Cancel every running job (e.g. before quitting). Prints and jobs past their commit keep
+    /// running; the report lists them.
+    pub fn cancel_all_jobs(&mut self) -> CancelReport {
         let ids: Vec<JobId> = self.jobs.running.iter().map(|r| r.id).collect();
+        self.cancel_each(ids)
+    }
+
+    fn cancel_each(&mut self, ids: Vec<JobId>) -> CancelReport {
+        let mut report = CancelReport::default();
         for id in ids {
-            self.cancel_job(id);
+            match self.try_cancel_job(id) {
+                Ok(()) => report.cancelled.push(id),
+                Err(why) => report.refused.push((id, why)),
+            }
         }
+        report
     }
 
     /// Is any job running? (Cheap: the UI asks every frame.)
@@ -1152,17 +1259,17 @@ impl Session {
         Some(format!("“{}” is still running on this document; wait for it to finish or cancel it (Esc)", job.label))
     }
 
-    /// Cancel the jobs editing document `doc` (it is closing).
-    pub(crate) fn cancel_jobs_on(&mut self, doc: DocId) {
+    /// Cancel the jobs editing document `doc` (it is closing). A job past its commit keeps
+    /// running and its result is still applied (see [`JobCtx::commit`]).
+    pub(crate) fn cancel_jobs_on(&mut self, doc: DocId) -> CancelReport {
         let ids: Vec<JobId> = self.jobs.running.iter().filter(|r| r.doc == Some(doc)).map(|r| r.id).collect();
-        for id in ids {
-            self.cancel_job(id);
-        }
+        let report = self.cancel_each(ids);
         // Workers cancelled now, or earlier and still unwinding, hold the closing document.
         #[cfg(not(target_arch = "wasm32"))]
         for d in self.jobs.draining.iter_mut().filter(|d| d.doc == Some(doc)) {
             d.release = true;
         }
+        report
     }
 
     /// Run the command `id`: inline, or (with `background`) as a job when it is one.
@@ -1399,6 +1506,10 @@ impl Session {
         }
         let prev_active = self.active;
         let target = match doc {
+            // A job past its commit has done its work outside the session (a save wrote its
+            // file); a closed document doesn't undo that, so its result still applies, to no
+            // document.
+            Some(d) if job.ctx.committed() && !self.documents().iter().any(|st| st.doc.id == *d) => None,
             Some(d) => {
                 let i =
                     self.documents().iter().position(|st| st.doc.id == *d).ok_or_else(|| EngineError::Other(format!("`{label}`: the document was closed")))?;
@@ -1524,19 +1635,15 @@ pub fn specs() -> Vec<crate::commands::CommandSpec> {
             params: r##"{"job":u64? (default: every running job)}"##,
             enabled: |_| Ok(()),
             run: |s, p| match p.get("job") {
-                None | Some(Value::Null) => {
-                    let n = s.jobs.running.len();
-                    s.cancel_all_jobs();
-                    Ok(json!({"cancelled": n.saturating_sub(s.jobs.running.len())}))
-                }
+                None | Some(Value::Null) => Ok(s.cancel_all_jobs().to_json()),
                 Some(v) => {
                     let id = v.as_u64().ok_or_else(|| EngineError::BadParams { cmd: "jobs.cancel".into(), msg: "`job` must be a job id".into() })?;
-                    if s.cancel_job(JobId(id)) {
-                        Ok(json!({"cancelled": 1}))
-                    } else if s.job(JobId(id)).is_some() {
-                        Err(EngineError::Other("printing cannot be cancelled here; use the system print queue".into()))
-                    } else {
-                        Err(EngineError::Other(format!("no running job {id}")))
+                    match s.try_cancel_job(JobId(id)) {
+                        Ok(()) => Ok(json!({"cancelled": 1})),
+                        // Not an error: the job is fine and will report how it ended.
+                        Err(why @ CancelRefused::Committing) => Ok(CancelReport { cancelled: Vec::new(), refused: vec![(JobId(id), why)] }.to_json()),
+                        Err(CancelRefused::Printing) => Err(EngineError::Other("printing cannot be cancelled here; use the system print queue".into())),
+                        Err(CancelRefused::NotRunning) => Err(EngineError::Other(format!("no running job {id}"))),
                     }
                 }
             },
diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index 38cca3b206..51ff64385c 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -422,6 +422,207 @@ fn jobs_cancel_command_and_bad_params() {
     assert_eq!(s.execute("jobs.cancel", json!({})).unwrap()["cancelled"], 0);
 }
 
+/// A fake save of the active document to `target`, gated by the test: it waits for `go`, calls
+/// [`JobCtx::commit`] and reports whether it got through, then waits for `finish` and replaces
+/// the file. `done` disconnects once the worker has returned.
+struct GatedSave {
+    id: JobId,
+    go: std::sync::mpsc::Sender<()>,
+    committed: std::sync::mpsc::Receiver<bool>,
+    finish: std::sync::mpsc::Sender<()>,
+    done: std::sync::mpsc::Receiver<()>,
+}
+
+impl GatedSave {
+    fn start(s: &mut Session, target: &std::path::Path) -> Self {
+        let (go, go_rx) = std::sync::mpsc::channel();
+        let (committed_tx, committed) = std::sync::mpsc::channel();
+        let (finish, finish_rx) = std::sync::mpsc::channel::<()>();
+        let (done_tx, done) = std::sync::mpsc::channel::<()>();
+        let target = target.to_path_buf();
+        let id = job(s
+            .start_job(
+                "file.save",
+                json!({"path": target}),
+                "Saving w.psd",
+                true,
+                move |ctx| {
+                    let _done = done_tx;
+                    go_rx.recv().ok();
+                    let r = ctx.commit();
+                    committed_tx.send(r.is_ok()).ok();
+                    r?;
+                    finish_rx.recv().ok();
+                    std::fs::write(&target, b"new").map_err(|e| EngineError::Other(e.to_string()))?;
+                    Ok(target.display().to_string())
+                },
+                |_, path: String| Ok(json!({"path": path})),
+            )
+            .unwrap());
+        Self { id, go, committed, finish, done }
+    }
+
+    /// Let the worker reach its commit; true if it committed.
+    fn commit(&self) -> bool {
+        self.go.send(()).unwrap();
+        self.committed.recv_timeout(Duration::from_secs(60)).unwrap()
+    }
+
+    /// Let a committed worker write the file.
+    fn finish(&self) {
+        self.finish.send(()).unwrap();
+    }
+
+    /// Block until the worker has returned.
+    fn join(&self) {
+        assert!(matches!(self.done.recv_timeout(Duration::from_secs(60)), Err(std::sync::mpsc::RecvTimeoutError::Disconnected)));
+    }
+}
+
+/// A job on the active document that runs until it is cancelled.
+fn open_job(s: &mut Session) -> JobId {
+    job(s
+        .start_job(
+            "test.spin",
+            json!({}),
+            "Spinning",
+            true,
+            |ctx| loop {
+                ctx.check()?;
+                std::thread::sleep(Duration::from_millis(1));
+            },
+            |_, ()| Ok(json!(null)),
+        )
+        .unwrap())
+}
+
+fn index_of(s: &Session, doc: photocraft_doc::DocId) -> usize {
+    s.documents().iter().position(|st| st.doc.id == doc).unwrap()
+}
+
+#[test]
+fn cancelling_a_save_before_it_commits_stops_it_without_touching_the_target() {
+    let dir = tmp_dir("cancel-before-commit");
+    let target = dir.join("w.psd");
+    std::fs::write(&target, b"old").unwrap();
+    let mut s = session(64, 64);
+    let save = GatedSave::start(&mut s, &target);
+    assert_eq!(s.execute("jobs.cancel", json!({"job": save.id.0})).unwrap(), json!({"cancelled": 1}));
+    assert_eq!(wait_event(&mut s, save.id).outcome, JobOutcome::Cancelled);
+    // The worker learns it lost at its commit point and writes nothing.
+    assert!(!save.commit(), "commit after a cancel must fail");
+    save.join();
+    assert_eq!(std::fs::read(&target).unwrap(), b"old", "target untouched");
+    assert!(s.job(save.id).is_none());
+}
+
+#[test]
+fn cancelling_a_committed_save_is_refused_and_it_reports_its_real_outcome() {
+    let dir = tmp_dir("cancel-after-commit");
+    let target = dir.join("w.psd");
+    std::fs::write(&target, b"old").unwrap();
+    let mut s = session(64, 64);
+    let save = GatedSave::start(&mut s, &target);
+    assert!(save.commit());
+    // Every single-job entry point says it was not cancelled.
+    assert!(!s.cancel_job(save.id));
+    assert_eq!(s.try_cancel_job(save.id), Err(CancelRefused::Committing));
+    assert_eq!(
+        s.execute("jobs.cancel", json!({"job": save.id.0})).unwrap(),
+        json!({"cancelled": 0, "notCancelled": [{"job": save.id.0, "reason": "committing"}]})
+    );
+    assert!(s.job(save.id).is_some(), "still running, document still locked");
+    assert!(s.poll_jobs().is_empty(), "no Cancelled event");
+    save.finish();
+    let e = wait_event(&mut s, save.id);
+    assert_eq!(e.outcome, JobOutcome::Done(json!({"path": target.display().to_string()})));
+    save.join();
+    assert_eq!(std::fs::read(&target).unwrap(), b"new");
+}
+
+#[test]
+fn cancel_all_cancels_open_jobs_and_reports_a_committed_save_it_left_running() {
+    let dir = tmp_dir("cancel-all-mixed");
+    let (committed_target, open_target) = (dir.join("a.psd"), dir.join("c.psd"));
+    std::fs::write(&committed_target, b"old").unwrap();
+    std::fs::write(&open_target, b"old").unwrap();
+    let mut s = session(64, 64);
+    let committed = GatedSave::start(&mut s, &committed_target);
+    assert!(committed.commit());
+    s.execute("file.new", json!({"width": 8, "height": 8})).unwrap();
+    let spinning = open_job(&mut s);
+    s.execute("file.new", json!({"width": 8, "height": 8})).unwrap();
+    let open = GatedSave::start(&mut s, &open_target);
+
+    let report = s.cancel_all_jobs();
+    assert_eq!(report.cancelled, vec![spinning, open.id]);
+    assert_eq!(report.refused, vec![(committed.id, CancelRefused::Committing)]);
+    assert_eq!(report.to_json(), json!({"cancelled": 2, "notCancelled": [{"job": committed.id.0, "reason": "committing"}]}));
+    // `jobs.cancel {}` again: only the committed save is left, and it is still not cancelled.
+    assert_eq!(s.execute("jobs.cancel", json!({})).unwrap(), json!({"cancelled": 0, "notCancelled": [{"job": committed.id.0, "reason": "committing"}]}));
+
+    // One poll reports both cancellations.
+    let ended: Vec<_> = s.poll_jobs().into_iter().map(|e| (e.id, e.outcome)).collect();
+    assert_eq!(ended, vec![(spinning, JobOutcome::Cancelled), (open.id, JobOutcome::Cancelled)]);
+    assert!(!open.commit());
+    open.join();
+    assert_eq!(std::fs::read(&open_target).unwrap(), b"old");
+    committed.finish();
+    assert!(matches!(wait_event(&mut s, committed.id).outcome, JobOutcome::Done(_)));
+    committed.join();
+    assert_eq!(std::fs::read(&committed_target).unwrap(), b"new");
+    assert!(s.jobs().is_empty());
+}
+
+#[test]
+fn closing_documents_cancels_open_saves_but_a_committed_save_finishes() {
+    let dir = tmp_dir("cancel-on-close-mixed");
+    let (committed_target, open_target) = (dir.join("a.psd"), dir.join("c.psd"));
+    std::fs::write(&committed_target, b"old").unwrap();
+    std::fs::write(&open_target, b"old").unwrap();
+    let mut s = session(64, 64);
+    let a = s.active().unwrap().doc.id;
+    let committed = GatedSave::start(&mut s, &committed_target);
+    assert!(committed.commit());
+    s.execute("file.new", json!({"width": 8, "height": 8})).unwrap();
+    let b = s.active().unwrap().doc.id;
+    let spinning = open_job(&mut s);
+    s.execute("file.new", json!({"width": 8, "height": 8})).unwrap();
+    let c = s.active().unwrap().doc.id;
+    let open = GatedSave::start(&mut s, &open_target);
+
+    assert_eq!(s.cancel_jobs_on(a).refused, vec![(committed.id, CancelRefused::Committing)]);
+    s.close(index_of(&s, a));
+    s.close(index_of(&s, c));
+    assert_eq!(wait_event(&mut s, open.id).outcome, JobOutcome::Cancelled);
+    assert!(!open.commit());
+    open.join();
+    assert_eq!(std::fs::read(&open_target).unwrap(), b"old", "the open save's target is untouched");
+    // The other document's job is not affected.
+    assert!(s.job(spinning).is_some());
+    // The committed save outlives its document and reports what it did, not "document closed".
+    committed.finish();
+    assert_eq!(wait_event(&mut s, committed.id).outcome, JobOutcome::Done(json!({"path": committed_target.display().to_string()})));
+    committed.join();
+    assert_eq!(std::fs::read(&committed_target).unwrap(), b"new");
+    assert!(s.cancel_job(spinning));
+    assert_eq!(s.documents().iter().map(|st| st.doc.id).collect::<Vec<_>>(), vec![b]);
+}
+
+#[test]
+fn commit_and_cancel_race_with_exactly_one_winner() {
+    for _ in 0..200 {
+        let ctx = JobCtx::default();
+        let other = ctx.clone();
+        let t = std::thread::spawn(move || other.commit().is_ok());
+        let cancelled = ctx.try_cancel();
+        let committed = t.join().unwrap();
+        assert_ne!(cancelled, committed, "exactly one of commit and cancel wins");
+        assert_eq!(ctx.cancelled(), cancelled);
+        assert_eq!(ctx.committed(), committed);
+    }
+}
+
 #[test]
 fn non_job_commands_still_finish_inline_with_start() {
     let mut s = session(16, 16);
diff --git a/crates/ui-egui/src/control/dispatch.rs b/crates/ui-egui/src/control/dispatch.rs
index 7d9c6dd5cd..3c667480f6 100644
--- a/crates/ui-egui/src/control/dispatch.rs
+++ b/crates/ui-egui/src/control/dispatch.rs
@@ -5,6 +5,7 @@ use super::params::{
     input_object, merged_object, modifiers_from, num_field, ok, screen_point, uint_field, whole_object,
 };
 use super::{ControlRequest, DialogKind, Outcome, PhotocraftApp, SHELL_DIALOG, Tool, ToolEvent, Value, json, run_waiting, tool_event, wrap};
+use photocraft_engine::jobs::{CancelReport, JobId};
 
 /// A domain handler: `Some` when it owns the request's method, `None` to let the next one try.
 type Handler = fn(&mut PhotocraftApp, &egui::Context, &ControlRequest) -> Option<Outcome>;
@@ -123,20 +124,29 @@ fn execute_command(app: &mut PhotocraftApp, ctx: &egui::Context, req: &ControlRe
 fn jobs_cancel(app: &mut PhotocraftApp, p: &Value) -> Outcome {
     let all = p.get("job").is_none_or(Value::is_null);
     match p.get("job").and_then(Value::as_u64) {
-        Some(j) if app.session.job(photocraft_engine::jobs::JobId(j)).is_some() => {
-            let cancelled = crate::jobs_ui::cancel(app, photocraft_engine::jobs::JobId(j));
-            ok(json!({"cancelled": usize::from(cancelled)}))
-        }
+        // Same reply as the engine's `jobs.cancel`: `{cancelled: n}`, plus `notCancelled:
+        // [{job, reason}]` for the jobs left running (a save already writing its file, a print).
+        Some(j) if app.session.job(JobId(j)).is_some() => ok(cancel_each(app, vec![JobId(j)]).to_json()),
         Some(j) => err(format!("no running job {j}")),
         None if all => {
             let ids: Vec<_> = app.session.jobs().into_iter().map(|j| j.id).collect();
-            let cancelled = ids.into_iter().filter(|j| crate::jobs_ui::cancel(app, *j)).count();
-            ok(json!({"cancelled": cancelled}))
+            ok(cancel_each(app, ids).to_json())
         }
         None => err("`job` must be a job id"),
     }
 }
 
+fn cancel_each(app: &mut PhotocraftApp, ids: Vec<JobId>) -> CancelReport {
+    let mut report = CancelReport::default();
+    for id in ids {
+        match crate::jobs_ui::try_cancel(app, id) {
+            Ok(()) => report.cancelled.push(id),
+            Err(why) => report.refused.push((id, why)),
+        }
+    }
+    report
+}
+
 // ---- the shell: view state, windows, GPU, focus, screenshots ----
 
 fn shell_methods(app: &mut PhotocraftApp, ctx: &egui::Context, req: &ControlRequest) -> Option<Outcome> {
diff --git a/crates/ui-egui/src/jobs_ui.rs b/crates/ui-egui/src/jobs_ui.rs
index 760a7b6b48..a561b2438e 100644
--- a/crates/ui-egui/src/jobs_ui.rs
+++ b/crates/ui-egui/src/jobs_ui.rs
@@ -20,12 +20,12 @@
 //! The canvas keeps showing the pre-job state: workers never touch the session's documents.
 
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::mpsc::Sender;
 
 use egui::{Color32, Rect, RichText, Sense, Stroke, vec2};
 use photocraft_doc::DocId;
-use photocraft_engine::jobs::{JobCtx, JobEvent, JobId, JobInfo, JobOutcome, OPEN_JOB, OpenSource, Started};
+use photocraft_engine::jobs::{CancelRefused, JobCtx, JobEvent, JobId, JobInfo, JobOutcome, OPEN_JOB, OpenSource, Started};
 use serde_json::{Value, json};
 
 use crate::theme::Tokens;
@@ -73,23 +73,14 @@ pub(crate) struct OpenBatch {
 /// The job command of a background save.
 pub const SAVE_JOB: &str = "file.save";
 
-const ENCODING: u8 = 0;
-const WRITING: u8 = 1;
-const CANCELLED: u8 = 2;
-
-/// A save worker's stage, shared between the worker and the UI.
+/// A save worker's state, shared between the worker and the UI. Whether it may still be
+/// cancelled is its job's ([`JobCtx::commit`]), so every cancel path agrees.
 #[derive(Debug, Default)]
 pub struct SaveState {
-    stage: AtomicU8,
     finished: AtomicBool,
 }
 
 impl SaveState {
-    /// Cancel unless writing has started; false once it has.
-    fn try_cancel(&self) -> bool {
-        matches!(self.stage.compare_exchange(ENCODING, CANCELLED, Ordering::AcqRel, Ordering::Acquire), Ok(_) | Err(CANCELLED))
-    }
-
     /// The worker has returned (or unwound): nothing of this save can still touch the file.
     pub fn finished(&self) -> bool {
         self.finished.load(Ordering::Acquire)
@@ -110,7 +101,6 @@ impl Drop for WorkerDone {
 /// be cancelled.
 pub struct SaveCtl {
     pub job: JobCtx,
-    state: Arc<SaveState>,
 }
 
 impl SaveCtl {
@@ -120,15 +110,15 @@ impl SaveCtl {
 
     /// `Err` once the save was cancelled: stop, write nothing.
     pub fn check(&self) -> Result<(), String> {
-        if self.job.cancelled() || self.state.stage.load(Ordering::Acquire) == CANCELLED { Err(SAVE_CANCELLED.into()) } else { Ok(()) }
+        if self.job.cancelled() { Err(SAVE_CANCELLED.into()) } else { Ok(()) }
     }
 
     /// Call once, right before replacing the file. `Ok`: the save can no longer be cancelled
-    /// (Cancel and Esc are refused) and must run to the end; `Err`: it was cancelled first and
-    /// nothing may be written.
+    /// (Cancel, Esc, `jobs.cancel`, cancelling every job and closing the document all leave it
+    /// running) and must run to the end; `Err`: it was cancelled first and nothing may be
+    /// written.
     pub fn commit(&self) -> Result<(), String> {
-        self.check()?;
-        self.state.stage.compare_exchange(ENCODING, WRITING, Ordering::AcqRel, Ordering::Acquire).map(|_| ()).map_err(|_| SAVE_CANCELLED.into())
+        self.job.commit().map_err(|_| SAVE_CANCELLED.into())
     }
 }
 
@@ -311,8 +301,8 @@ pub fn start_save(
         &label,
         true,
         move |ctx| {
-            let _done = WorkerDone(Arc::clone(&worker));
-            let ctl = SaveCtl { job: ctx.clone(), state: worker };
+            let _done = WorkerDone(worker);
+            let ctl = SaveCtl { job: ctx.clone() };
             save(&snapshot, &target, &settings, &ctl)
                 .map_err(|e| if ctl.check().is_err() { photocraft_engine::EngineError::Cancelled } else { photocraft_engine::EngineError::Other(e) })
         },
@@ -447,25 +437,27 @@ pub fn job_in_view(app: &PhotocraftApp) -> Option<JobInfo> {
 
 /// Cancel job `id` (the status bar's ×, the dialog's Cancel, Esc, closing an opening tab).
 pub fn cancel(app: &mut PhotocraftApp, id: JobId) -> bool {
+    try_cancel(app, id).is_ok()
+}
+
+/// [`cancel`], saying why a job was left running.
+pub fn try_cancel(app: &mut PhotocraftApp, id: JobId) -> Result<(), CancelRefused> {
     let label = app.session.job(id).map(|j| j.label);
+    let r = app.session.try_cancel_job(id);
     // A save that has started replacing the file runs to the end: cancelling it now would leave
     // the file written but the document marked unsaved.
-    if let Some(save) = app.jobs.saves.iter().find(|s| s.job == id)
-        && !save.state.try_cancel()
-    {
+    if r == Err(CancelRefused::Committing) {
         app.ui.status = crate::i18n::fmt(tl!("{label} is writing the file and can no longer be cancelled"), &[("label", label.as_deref().unwrap_or_default())]);
         app.ui.status_error = false;
-        return false;
     }
-    let cancelled = app.session.cancel_job(id);
-    if cancelled {
+    if r.is_ok() {
         // The event (and its status text) arrives with the next poll; say so now as well.
         if let Some(l) = label {
             app.ui.status = crate::i18n::fmt(tl!("Cancelled {label}"), &[("label", &l)]);
             app.ui.status_error = false;
         }
     }
-    cancelled
+    r
 }
 
 /// Handles one finished job: optional completion beep, waiting control replies, and the
diff --git a/crates/ui-egui/src/jobs_ui/tests.rs b/crates/ui-egui/src/jobs_ui/tests.rs
index ffb6207fd4..41d5e127b0 100644
--- a/crates/ui-egui/src/jobs_ui/tests.rs
+++ b/crates/ui-egui/src/jobs_ui/tests.rs
@@ -604,6 +604,95 @@ fn a_save_that_has_started_writing_cannot_be_cancelled() {
     assert!(!h.state().session.active().unwrap().is_dirty(), "the written save is recorded");
 }
 
+/// A `save_file` service held by `gates` that really replaces the file: it encodes until
+/// `encode` opens, commits, then writes `new` once `write` opens.
+fn file_save(gates: &Gates) -> crate::SaveFileFn {
+    let g = gates.clone();
+    Arc::new(move |_, path, _, ctl| {
+        ctl.progress(0.0, "Encoding");
+        while !g.encode.load(Ordering::Relaxed) {
+            ctl.check()?;
+            std::thread::sleep(Duration::from_millis(1));
+        }
+        ctl.commit()?;
+        ctl.progress(0.0, "Writing");
+        while !g.write.load(Ordering::Relaxed) {
+            std::thread::sleep(Duration::from_millis(1));
+        }
+        std::fs::write(path, b"new").map_err(|e| e.to_string())?;
+        Ok(Vec::new())
+    })
+}
+
+/// A file holding `old`, in a fresh directory named for the test.
+fn old_file(test: &str) -> String {
+    let dir = std::env::temp_dir().join(format!("photocraft-jobs-ui-{}-{test}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("w.psd");
+    std::fs::write(&path, b"old").unwrap();
+    path.to_string_lossy().into_owned()
+}
+
+fn control(h: &mut Harness<'static, PhotocraftApp>, method: &str, params: Value) -> Value {
+    let (req, _rx) = crate::ControlRequest::new(method, params);
+    let ctx = h.ctx.clone();
+    let crate::control::Outcome::Done(v) = crate::control::handle(h.state_mut(), &ctx, &req) else { panic!("{method} replies at once") };
+    v
+}
+
+#[test]
+fn jobs_cancel_before_a_save_writes_stops_it_and_leaves_the_target_untouched() {
+    let mut h = app_harness();
+    let path = old_file("cancel-before-write");
+    let gates = Gates::default();
+    h.state_mut().services.save_file = Some(file_save(&gates));
+    h.state_mut().save_as(Some(path.clone())).unwrap();
+    h.run_steps(2);
+    let job = h.state().jobs.saves[0].job;
+    let v = control(&mut h, "jobs.cancel", json!({"job": job.0}));
+    assert_eq!(v["result"], json!({"cancelled": 1}), "{v}");
+    // The worker reaches its commit point only now, and must give up there.
+    gates.encode.store(true, Ordering::Relaxed);
+    gates.write.store(true, Ordering::Relaxed);
+    step_until(&mut h, |a| !a.saving());
+    assert_eq!(std::fs::read(&path).unwrap(), b"old", "target untouched");
+    let st = h.state().session.active().unwrap();
+    assert!(st.is_dirty() && st.path.is_none(), "the document is not marked saved");
+    assert_eq!(h.state().ui.status, "Cancelled Saving w.psd");
+}
+
+#[test]
+fn jobs_cancel_during_the_write_reports_the_save_as_not_cancelled_and_it_finishes() {
+    let mut h = app_harness();
+    let path = old_file("cancel-during-write");
+    let gates = Gates { encode: Arc::new(AtomicBool::new(true)), ..Gates::default() };
+    h.state_mut().services.save_file = Some(file_save(&gates));
+    h.state_mut().save_as(Some(path.clone())).unwrap();
+    let saved_doc = h.state().session.active().unwrap().doc.id;
+    until_writing(&mut h);
+    let save = h.state().jobs.saves[0].job;
+    // A second document with a job that can still be cancelled.
+    h.state_mut().session.execute("file.new", json!({"width": 32, "height": 32})).unwrap();
+    let slow = slow_job(h.state_mut(), &Arc::new(AtomicBool::new(false)));
+
+    let refused = json!([{"job": save.0, "reason": "committing"}]);
+    let v = control(&mut h, "jobs.cancel", json!({"job": save.0}));
+    assert_eq!(v["result"], json!({"cancelled": 0, "notCancelled": refused}), "{v}");
+    assert_eq!(h.state().ui.status, "Saving w.psd is writing the file and can no longer be cancelled");
+    // Cancel everything: the other job stops, the save is reported as left running.
+    let v = control(&mut h, "jobs.cancel", json!({}));
+    assert_eq!(v["result"], json!({"cancelled": 1, "notCancelled": refused}), "{v}");
+    assert!(h.state().session.job(slow).is_none());
+    assert!(h.state().session.job(save).is_some(), "the save still runs and keeps its document locked");
+
+    gates.write.store(true, Ordering::Relaxed);
+    step_until(&mut h, |a| !a.saving());
+    assert_eq!(std::fs::read(&path).unwrap(), b"new");
+    let st = h.state().session.documents().iter().find(|st| st.doc.id == saved_doc).unwrap();
+    assert!(!st.is_dirty() && st.path.as_deref() == Some(path.as_str()), "the save that happened is recorded");
+}
+
 /// #3389: like Photoshop, a running save reads "Saving 45%" in the status bar and appends
 /// " - Saving 45%" to its document's tab title, in both tab strips; both go when it ends.
 #[test]
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index e74938dc2f..39f5d2cbc2 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -250,7 +250,7 @@ The shape is pinned by a test in `crates/automation/src/rpc.rs` (#3684).
 
 ### Background jobs (#210)
 
-Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
+Long commands (every `filter.*`, `edit.contentAwareFill`, `edit.contentAwareScale`, `file.automate.photomerge`, `brush.presets.importAbr`), file opens and interactive saves (File › Save, Save As and the TIFF Options continuation, #2017) run as background jobs in the desktop app: the window keeps drawing, the status bar shows progress with a Cancel button, and jobs that lock the active document show a modal progress dialog (Esc cancels). `engine.execute`, `ui.menu.invoke`, `ui.dialog.confirm` and `app.save` still wait for the result by default; pass `"wait": false` to get `{job, pending: true}` at once, then poll `jobs.list` (`state`: running, done, failed, cancelled; `progress` 0–1; the result or error) and stop it with `jobs.cancel {job}`. A cancelled or failed job leaves the document unchanged. A save that has started replacing its file can no longer be cancelled: `jobs.cancel` leaves it running and lists it in `notCancelled: [{job, reason: "committing"}]` (next to `cancelled`, the number of jobs it did cancel); the save then ends as done or failed like any other. Closing its document doesn't stop it either. While a job runs, commands that would edit its document fail with "… is still running on this document". `ui.inspect` reports `jobs` (running jobs, opening files, saving files). Set `PHOTOCRAFT_INLINE_JOBS=1` to run everything inline.
 
 ## Preferences
 
@@ -440,7 +440,7 @@ stdio, and a value that is not a port is a usage error naming the variable. Impl
 | Method | Params |
 |---|---|
 | `engine.execute` | `{command, params?, wait?}`: any engine command (`wait: false` starts a long one as a background job: `{job, pending}`) |
-| `jobs.list` / `jobs.cancel` | `{}` / `{job?}`: background jobs; cancel one or all. Every request (and MCP tool call) first applies the jobs that finished, so `doc.save`, `doc.inspect`, `doc.render` and `session.list` include a finished job's result without polling `jobs.list` first |
+| `jobs.list` / `jobs.cancel` | `{}` / `{job?}`: background jobs; cancel one or all (`{cancelled: n}`, plus `notCancelled: [{job, reason}]` for jobs left running, e.g. a save already writing its file). Every request (and MCP tool call) first applies the jobs that finished, so `doc.save`, `doc.inspect`, `doc.render` and `session.list` include a finished job's result without polling `jobs.list` first |
 | `engine.commands` | `{filter?}`: registry with params docs and enablement (`enabled`, `disabledReason`, `needsDocument`); `result` is a bare array of command objects ([Command list replies](#command-list-replies)) |
 | `session.list` | open documents and the active index |
 | `doc.open` / `doc.new` | `{path, approveHighMemory? (false)}` / `file.new` params (`approveHighMemory` is the same one-shot PSD/PSB consent as the `file.openAs` command; see [development.md](development.md) for the structured refusal fields) |

From f67696cb2c0ca3bcf63686f25677da7a0fa4f44c Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 16:42:18 +0100
Subject: [PATCH 104/109] Jobs tests: give the gated-save tests a temp dir on
 every platform

The cancel-path tests used the Unix-only tmp_dir fixture, so the engine's lib
tests did not compile on Windows (E0425 in CI run 41660911095). They get their
own save_dir helper instead.
---
 crates/engine/src/jobs/tests.rs | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/crates/engine/src/jobs/tests.rs b/crates/engine/src/jobs/tests.rs
index 51ff64385c..70443bc523 100644
--- a/crates/engine/src/jobs/tests.rs
+++ b/crates/engine/src/jobs/tests.rs
@@ -479,6 +479,15 @@ impl GatedSave {
     }
 }
 
+/// A fresh directory for a [`GatedSave`] test (on every platform, unlike the Unix-only
+/// fixtures' `tmp_dir`).
+fn save_dir(name: &str) -> std::path::PathBuf {
+    let d = std::env::temp_dir().join(format!("photocraft-engine-gated-save-{}-{name}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&d);
+    std::fs::create_dir_all(&d).unwrap();
+    d
+}
+
 /// A job on the active document that runs until it is cancelled.
 fn open_job(s: &mut Session) -> JobId {
     job(s
@@ -502,7 +511,7 @@ fn index_of(s: &Session, doc: photocraft_doc::DocId) -> usize {
 
 #[test]
 fn cancelling_a_save_before_it_commits_stops_it_without_touching_the_target() {
-    let dir = tmp_dir("cancel-before-commit");
+    let dir = save_dir("cancel-before-commit");
     let target = dir.join("w.psd");
     std::fs::write(&target, b"old").unwrap();
     let mut s = session(64, 64);
@@ -518,7 +527,7 @@ fn cancelling_a_save_before_it_commits_stops_it_without_touching_the_target() {
 
 #[test]
 fn cancelling_a_committed_save_is_refused_and_it_reports_its_real_outcome() {
-    let dir = tmp_dir("cancel-after-commit");
+    let dir = save_dir("cancel-after-commit");
     let target = dir.join("w.psd");
     std::fs::write(&target, b"old").unwrap();
     let mut s = session(64, 64);
@@ -542,7 +551,7 @@ fn cancelling_a_committed_save_is_refused_and_it_reports_its_real_outcome() {
 
 #[test]
 fn cancel_all_cancels_open_jobs_and_reports_a_committed_save_it_left_running() {
-    let dir = tmp_dir("cancel-all-mixed");
+    let dir = save_dir("cancel-all-mixed");
     let (committed_target, open_target) = (dir.join("a.psd"), dir.join("c.psd"));
     std::fs::write(&committed_target, b"old").unwrap();
     std::fs::write(&open_target, b"old").unwrap();
@@ -576,7 +585,7 @@ fn cancel_all_cancels_open_jobs_and_reports_a_committed_save_it_left_running() {
 
 #[test]
 fn closing_documents_cancels_open_saves_but_a_committed_save_finishes() {
-    let dir = tmp_dir("cancel-on-close-mixed");
+    let dir = save_dir("cancel-on-close-mixed");
     let (committed_target, open_target) = (dir.join("a.psd"), dir.join("c.psd"));
     std::fs::write(&committed_target, b"old").unwrap();
     std::fs::write(&open_target, b"old").unwrap();

From ae0da189a2bd1365eba9ea19b7b0f4f809f6af00 Mon Sep 17 00:00:00 2001
From: David Mann <daaavid.mann@gmail.com>
Date: Tue, 3 Nov 2026 17:26:39 +0100
Subject: [PATCH 105/109] Address CodeRabbit review: a cancel after an action's
 saved snapshot keeps that file

When an action saves and then closes or switches away, Batch writes the
saved snapshot inside the action closure. A cancel landing after that write
made process_one return Cancelled, so the input was reported as skipped
although its output exists. The snapshot write is now final: the cancel
stops only the inputs after it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/file_cmds/batch_run.rs | 23 +++++++++++---------
 crates/engine/src/cmd/file_cmds/tests.rs     | 22 +++++++++++++++++++
 2 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/crates/engine/src/cmd/file_cmds/batch_run.rs b/crates/engine/src/cmd/file_cmds/batch_run.rs
index 5a93e670a8..1a981298c0 100644
--- a/crates/engine/src/cmd/file_cmds/batch_run.rs
+++ b/crates/engine/src/cmd/file_cmds/batch_run.rs
@@ -221,24 +221,27 @@ fn process_one(raw_ppi: f64, path: &str, out: &str, save: SaveOpts, options: Pro
         ctx.publish_batch_preview(path, scratch.active().map(|state| state.doc.clone()));
     }
     let saved_by_action = f(&mut scratch, out)?;
+    if saved_by_action {
+        // The action's saved snapshot is already written: a cancel or Esc arriving now stops the
+        // inputs after this one, not this result.
+        return Ok(());
+    }
     if let Some(ctx) = options.ctx {
         ctx.check()?;
         if ctx.batch_interrupt_requested() {
             return Err(EngineError::Cancelled);
         }
     }
-    if !saved_by_action {
-        let d = scratch.active().ok_or(EngineError::NoDocument)?;
-        if let Some(format) = options.format {
-            let ext = if format == "same" { same_format(path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
-            if let Some(ctx) = options.ctx {
-                save_batch_doc(&d.doc, out, &ext, save, ctx)?;
-            } else {
-                save_doc_as(&d.doc, out, &ext, save)?;
-            }
+    let d = scratch.active().ok_or(EngineError::NoDocument)?;
+    if let Some(format) = options.format {
+        let ext = if format == "same" { same_format(path) } else { format.trim_start_matches('.').to_ascii_lowercase() };
+        if let Some(ctx) = options.ctx {
+            save_batch_doc(&d.doc, out, &ext, save, ctx)?;
         } else {
-            save_doc(&d.doc, out, save)?;
+            save_doc_as(&d.doc, out, &ext, save)?;
         }
+    } else {
+        save_doc(&d.doc, out, save)?;
     }
     Ok(())
 }
diff --git a/crates/engine/src/cmd/file_cmds/tests.rs b/crates/engine/src/cmd/file_cmds/tests.rs
index 1334cb77a2..804e6a01ca 100644
--- a/crates/engine/src/cmd/file_cmds/tests.rs
+++ b/crates/engine/src/cmd/file_cmds/tests.rs
@@ -89,6 +89,28 @@ fn batch_cancelled_during_an_action_does_not_save_that_input() {
     assert!(!std::path::Path::new(&out).exists());
 }
 
+/// An action that saved and then closed its document has its saved snapshot written by the time
+/// it returns: a cancel landing then counts that file as written, not skipped.
+#[test]
+fn batch_cancel_after_a_saved_snapshot_is_written_keeps_that_file() {
+    let dir = tmp("batch-cancel-after-snapshot");
+    let first = png(&dir, "first.png", 8, 6, "#ff0000");
+    let second = png(&dir, "second.png", 8, 6, "#00ff00");
+    let first_out = join(&dir, "out/first.png");
+    let ctx = crate::jobs::JobCtx::new();
+    let policy = super::batch_run::BatchPolicy { stop_on_error: false, error_log: None };
+    let outputs = vec![(first, first_out.clone()), (second.clone(), join(&dir, "out/second.png"))];
+    let result = super::batch_run::process_batch_outputs(72.0, outputs, "png", SaveOpts::default(), &policy, &ctx, &|s, out| {
+        save_doc(&s.active().unwrap().doc, out, None).unwrap();
+        ctx.cancel();
+        Ok(true)
+    })
+    .unwrap();
+    assert_eq!(result["files"], json!([first_out]), "{result}");
+    assert_eq!(result["skipped"], json!([second]), "{result}");
+    assert_eq!(result["cancelled"], json!(true), "{result}");
+}
+
 /// A cancel that lands while an input fails on its own keeps that failure and its reason; only
 /// the inputs after it are skipped.
 #[test]

From d21c403e5f8a127bdc63e584f574bdbd8c9dd08a Mon Sep 17 00:00:00 2001
From: Tareq Halaby <tareq.halaby@gmail.com>
Date: Tue, 3 Nov 2026 17:55:35 +0100
Subject: [PATCH 106/109] Type: add OpenType Numerals submenu (figure styles)
 (#11051)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Type: add OpenType Numerals submenu (figure styles)

Type › OpenType › Numerals sets lnum/onum/pnum/tnum as a radio style
(Default through Tabular Oldstyle). Checkmarks follow the selection
start; TYPE-218-5 scorecard/gaps updated; parity floor 640.

* refactor(engine): one style-at-character lookup for the OpenType menus

feature_on_at and numerals_style_at each walked the runs the same way;
they now share style_at. NumeralsStyle::from_id and numerals_style_of
read the existing tables instead of repeating them.

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

* fix(text): persist OpenType numeral tags through PSD EngineData

Map lnum/pnum/tnum as EngineData bools and the width×height combos as
FigureStyle (Krita/Illustrator), so Numerals choices survive PSD round-trip.

* docs(gaps): note Numerals PSD figure-tag round-trip

* revert(text): keep PSD EngineData to the keys Photoshop writes

Backs out the PSD half of 18610324 and its gaps note (58813de3); the
engine reformat in that commit stays.

- `LiningFigures`, `ProportionalFigures` and `TabularFigures` are not
  Photoshop EngineData keys (the commit says Photoshop only has
  `OldStyle`), so writing them puts keys of our own into users' PSDs.
- The `/FigureStyle` code table (1-4) has no oracle: no Photoshop-authored
  file in photocraft-corpus, and neither ag-psd nor psd-tools reads it.

AGENTS.md rule 3 asks for public specs or observation. PSD persistence
of the numeral styles can come back with a Photoshop-authored oracle.
The Numerals menu still round-trips through .pcraft.

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

* test(text): lock PSD EngineData to Photoshop OldStyle for numerals

Document AGENTS.md clean-room: only onum survives TySh round-trip; lnum/pnum/tnum stay .pcraft-only until a Photoshop-authored corpus oracle.

---------

Co-authored-by: FredApps <153173854+FredApps@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/type_extra_cmds.rs      | 182 +++++++++++++++++-
 .../engine/src/cmd/type_extra_cmds/tests.rs   | 132 +++++++++++++
 crates/text/src/tests.rs                      |  20 ++
 crates/ui-egui/src/menu_catalog.rs            |   9 +
 crates/ui-egui/src/menus/parity.rs            |   2 +-
 .../ui-egui/src/menus/view_cmds/dispatch.rs   |   9 +-
 crates/ui-egui/src/menus/view_cmds/tests.rs   |  20 ++
 docs/gaps.md                                  |   7 +-
 docs/parity-checklist.md                      |   4 +-
 docs/scorecard.md                             |   6 +-
 scorecard/type.toml                           |   2 +-
 11 files changed, 378 insertions(+), 15 deletions(-)

diff --git a/crates/engine/src/cmd/type_extra_cmds.rs b/crates/engine/src/cmd/type_extra_cmds.rs
index d8c11a52d6..566912b21c 100644
--- a/crates/engine/src/cmd/type_extra_cmds.rs
+++ b/crates/engine/src/cmd/type_extra_cmds.rs
@@ -1,6 +1,7 @@
 //! The Type menu: anti-aliasing, orientation, point ⇄ paragraph conversion, Create Work Path,
-//! Convert to Shape, Rasterize, Warp Text, the OpenType toggles, Paste Lorem Ipsum, Update All
-//! Text Layers, missing-font replacement and the default type styles.
+//! Convert to Shape, Rasterize, Warp Text, the OpenType toggles (with the Numerals submenu),
+//! Paste Lorem Ipsum, Update All Text Layers, missing-font replacement and the default type
+//! styles.
 //!
 //! Everything edits the typed [`TextLayer`] model and re-renders through `type_cmds::refresh`,
 //! so the PSD `TySh` data (and with it warp, anti-aliasing and the OpenType flags) is regenerated
@@ -502,6 +503,88 @@ fn warp_text(s: &mut Session, p: &Value) -> Result<Value> {
 
 // ---------- OpenType toggles ----------
 
+/// OpenType figure tags Type › OpenType › Numerals clears or sets (`lnum`/`onum`/`pnum`/`tnum`).
+pub const NUMERAL_FEATURE_TAGS: [&str; 4] = ["lnum", "onum", "pnum", "tnum"];
+
+/// One item of Type › OpenType › Numerals (Adobe figure-style radio set).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum NumeralsStyle {
+    Default,
+    Lining,
+    Oldstyle,
+    Proportional,
+    Tabular,
+    ProportionalLining,
+    TabularLining,
+    ProportionalOldstyle,
+    TabularOldstyle,
+}
+
+impl NumeralsStyle {
+    /// Command-id suffix after `type.openType.numerals.`.
+    pub const fn id(self) -> &'static str {
+        match self {
+            Self::Default => "default",
+            Self::Lining => "lining",
+            Self::Oldstyle => "oldstyle",
+            Self::Proportional => "proportional",
+            Self::Tabular => "tabular",
+            Self::ProportionalLining => "proportionalLining",
+            Self::TabularLining => "tabularLining",
+            Self::ProportionalOldstyle => "proportionalOldstyle",
+            Self::TabularOldstyle => "tabularOldstyle",
+        }
+    }
+
+    /// Menu label for this numerals style.
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Default => "Default",
+            Self::Lining => "Lining",
+            Self::Oldstyle => "Oldstyle",
+            Self::Proportional => "Proportional",
+            Self::Tabular => "Tabular",
+            Self::ProportionalLining => "Proportional Lining",
+            Self::TabularLining => "Tabular Lining",
+            Self::ProportionalOldstyle => "Proportional Oldstyle",
+            Self::TabularOldstyle => "Tabular Oldstyle",
+        }
+    }
+
+    /// Parse a `type.openType.numerals.*` suffix.
+    pub fn from_id(id: &str) -> Option<Self> {
+        Self::ALL.into_iter().find(|style| style.id() == id)
+    }
+
+    /// Every Numerals menu item, in menu order.
+    pub const ALL: [Self; 9] = [
+        Self::Default,
+        Self::Lining,
+        Self::Oldstyle,
+        Self::Proportional,
+        Self::Tabular,
+        Self::ProportionalLining,
+        Self::TabularLining,
+        Self::ProportionalOldstyle,
+        Self::TabularOldstyle,
+    ];
+
+    /// OpenType tags this style turns on (the other [`NUMERAL_FEATURE_TAGS`] are cleared).
+    pub const fn tags(self) -> &'static [&'static str] {
+        match self {
+            Self::Default => &[],
+            Self::Lining => &["lnum"],
+            Self::Oldstyle => &["onum"],
+            Self::Proportional => &["pnum"],
+            Self::Tabular => &["tnum"],
+            Self::ProportionalLining => &["pnum", "lnum"],
+            Self::TabularLining => &["tnum", "lnum"],
+            Self::ProportionalOldstyle => &["pnum", "onum"],
+            Self::TabularOldstyle => &["tnum", "onum"],
+        }
+    }
+}
+
 /// Is the OpenType toggle `tag` on for a character style? (`liga`/`dlig` have dedicated fields.)
 pub fn feature_on(st: &photocraft_doc::text::CharStyle, tag: &str) -> bool {
     match tag {
@@ -511,6 +594,36 @@ pub fn feature_on(st: &photocraft_doc::text::CharStyle, tag: &str) -> bool {
     }
 }
 
+/// The character style at character `ci` of `t`: its run's, or past the end the last run's.
+fn style_at(t: &TextLayer, ci: usize) -> Option<photocraft_doc::text::CharStyle> {
+    let at = byte_index(&t.text, ci);
+    let mut end = 0usize;
+    let mut last = None;
+    for run in t.char_runs() {
+        end = end.saturating_add(run.len);
+        if at < end {
+            return Some(run.style);
+        }
+        last = Some(run.style);
+    }
+    last
+}
+
+/// Is the OpenType toggle `tag` on at character `ci` of `t`? Past the end it reads the last run.
+pub fn feature_on_at(t: &TextLayer, ci: usize, tag: &str) -> bool {
+    style_at(t, ci).is_some_and(|st| feature_on(&st, tag))
+}
+
+/// Which Numerals menu item matches `st`'s figure tags? `None` when the mix is not a menu item.
+pub fn numerals_style_of(st: &photocraft_doc::text::CharStyle) -> Option<NumeralsStyle> {
+    NumeralsStyle::ALL.into_iter().find(|style| NUMERAL_FEATURE_TAGS.iter().all(|tag| feature_on(st, tag) == style.tags().contains(tag)))
+}
+
+/// Numerals style at character `ci` of `t` (same run pick as [`feature_on_at`]).
+pub fn numerals_style_at(t: &TextLayer, ci: usize) -> Option<NumeralsStyle> {
+    style_at(t, ci).and_then(|st| numerals_style_of(&st))
+}
+
 fn set_feature(st: &mut photocraft_doc::text::CharStyle, tag: &str, on: bool) {
     match tag {
         "liga" => st.ligatures = on,
@@ -524,13 +637,37 @@ fn set_feature(st: &mut photocraft_doc::text::CharStyle, tag: &str, on: bool) {
     }
 }
 
+fn apply_numerals(st: &mut photocraft_doc::text::CharStyle, style: NumeralsStyle) {
+    let on = style.tags();
+    for tag in NUMERAL_FEATURE_TAGS {
+        set_feature(st, tag, on.contains(&tag));
+    }
+}
+
+fn set_numerals(s: &mut Session, p: &Value, style: NumeralsStyle) -> Result<Value> {
+    with_text_targets(s, p, "Change OpenType Numerals", |t, (a, b)| {
+        style_range(t, a.min(b), a.max(b), &|st| apply_numerals(st, style));
+        Ok(())
+    })?;
+    Ok(json!({"numerals": style.id()}))
+}
+
 fn toggle_opentype(s: &mut Session, p: &Value, tag: &'static str) -> Result<Value> {
     let ids = format_targets(s, p)?;
     let st = s.active().ok_or(EngineError::NoDocument)?;
     let representative = st.active_layer.filter(|id| ids.contains(id)).or_else(|| ids.first().copied());
-    let cur = representative
-        .and_then(|id| st.doc.layer(id))
-        .is_some_and(|l| matches!(&l.content, LayerContent::Text(t) if t.char_runs().first().is_some_and(|r| feature_on(&r.style, tag))));
+    // The toggle direction follows the style where the edit starts: the range start on a single
+    // layer, else the first character.
+    let start_char = if p.get("layers").is_none() || p.get("layer").is_some() {
+        p.get("range").and_then(Value::as_array).filter(|r| r.len() == 2).map_or(0, |r| {
+            let a = r.first().and_then(Value::as_u64).unwrap_or(0);
+            let b = r.get(1).and_then(Value::as_u64).unwrap_or(a);
+            usize::try_from(a.min(b)).unwrap_or(usize::MAX)
+        })
+    } else {
+        0
+    };
+    let cur = representative.and_then(|id| st.doc.layer(id)).is_some_and(|l| matches!(&l.content, LayerContent::Text(t) if feature_on_at(t, start_char, tag)));
     let on = p.get("on").and_then(Value::as_bool).unwrap_or(!cur);
     with_text_targets(s, p, "Change OpenType Feature", |t, (a, b)| {
         style_range(t, a.min(b), a.max(b), &|st| set_feature(st, tag, on));
@@ -770,6 +907,41 @@ pub fn specs() -> Vec<CommandSpec> {
         spec!("type.openType.ornaments", "Ornaments", &["Type", "OpenType"], OT, has_format_target, |s, p| toggle_opentype(s, p, "ornm")),
         spec!("type.openType.ordinals", "Ordinals", &["Type", "OpenType"], OT, has_format_target, |s, p| toggle_opentype(s, p, "ordn")),
         spec!("type.openType.fractions", "Fractions", &["Type", "OpenType"], OT, has_format_target, |s, p| toggle_opentype(s, p, "frac")),
+        spec!("type.openType.numerals.default", "Default", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| set_numerals(
+            s,
+            p,
+            NumeralsStyle::Default
+        )),
+        spec!("type.openType.numerals.lining", "Lining", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| {
+            set_numerals(s, p, NumeralsStyle::Lining)
+        }),
+        spec!("type.openType.numerals.oldstyle", "Oldstyle", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| {
+            set_numerals(s, p, NumeralsStyle::Oldstyle)
+        }),
+        spec!("type.openType.numerals.proportional", "Proportional", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| set_numerals(
+            s,
+            p,
+            NumeralsStyle::Proportional
+        )),
+        spec!("type.openType.numerals.tabular", "Tabular", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| {
+            set_numerals(s, p, NumeralsStyle::Tabular)
+        }),
+        spec!("type.openType.numerals.proportionalLining", "Proportional Lining", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| {
+            set_numerals(s, p, NumeralsStyle::ProportionalLining)
+        }),
+        spec!("type.openType.numerals.tabularLining", "Tabular Lining", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| set_numerals(
+            s,
+            p,
+            NumeralsStyle::TabularLining
+        )),
+        spec!("type.openType.numerals.proportionalOldstyle", "Proportional Oldstyle", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| {
+            set_numerals(s, p, NumeralsStyle::ProportionalOldstyle)
+        }),
+        spec!("type.openType.numerals.tabularOldstyle", "Tabular Oldstyle", &["Type", "OpenType", "Numerals"], FP, has_format_target, |s, p| set_numerals(
+            s,
+            p,
+            NumeralsStyle::TabularOldstyle
+        )),
         spec!("type.createWorkPath", "Create Work Path", &["Type"], LP, has_text, create_work_path),
         spec!("type.convertToShape", "Convert to Shape", &["Type"], LP, has_text, convert_to_shape),
         spec!("type.rasterizeTypeLayer", "Rasterize Type Layer", &["Type"], LP, has_text, |s, p| s.execute("type.rasterize", p.clone())),
diff --git a/crates/engine/src/cmd/type_extra_cmds/tests.rs b/crates/engine/src/cmd/type_extra_cmds/tests.rs
index 8ae504cfa1..4008f82001 100644
--- a/crates/engine/src/cmd/type_extra_cmds/tests.rs
+++ b/crates/engine/src/cmd/type_extra_cmds/tests.rs
@@ -243,6 +243,138 @@ fn opentype_toggles_store_features() {
     assert!(feature_on(&back.char_runs()[0].style, "swsh") && !back.char_runs()[0].style.ligatures);
 }
 
+/// Is `tag` on at character `ci` of an ASCII text layer?
+fn on_at(s: &Session, id: LayerId, ci: usize, tag: &str) -> bool {
+    let mut end = 0;
+    text(s, id)
+        .char_runs()
+        .iter()
+        .find(|r| {
+            end += r.len;
+            ci < end
+        })
+        .is_some_and(|r| feature_on(&r.style, tag))
+}
+
+#[test]
+fn numerals_are_registered_with_their_menu_path() {
+    for style in NumeralsStyle::ALL {
+        let spec = crate::commands::find(&format!("type.openType.numerals.{}", style.id())).unwrap();
+        assert_eq!(spec.label, style.label());
+        assert_eq!(spec.menu, ["Type", "OpenType", "Numerals"]);
+    }
+    assert!(crate::commands::find("type.openType.numerals.unknown").is_none());
+}
+
+#[test]
+fn numerals_replace_figure_tags_and_keep_other_features() {
+    let mut s = session(8);
+    let id = text_layer(&mut s, "012345");
+    let before = text(&s, id).char_runs()[0].style.clone();
+    s.execute("type.openType.fractions", json!({"on": true})).unwrap();
+    s.execute("type.openType.numerals.tabularLining", json!({})).unwrap();
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::TabularLining));
+    assert!(on_at(&s, id, 0, "tnum") && on_at(&s, id, 0, "lnum") && !on_at(&s, id, 0, "onum") && !on_at(&s, id, 0, "pnum"));
+    assert!(feature_on(&text(&s, id).char_runs()[0].style, "frac"), "non-figure features stay");
+    s.execute("type.openType.numerals.proportionalOldstyle", json!({})).unwrap();
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::ProportionalOldstyle));
+    assert!(on_at(&s, id, 0, "pnum") && on_at(&s, id, 0, "onum") && !on_at(&s, id, 0, "tnum") && !on_at(&s, id, 0, "lnum"));
+    s.execute("type.openType.numerals.default", json!({})).unwrap();
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::Default));
+    for tag in NUMERAL_FEATURE_TAGS {
+        assert!(!on_at(&s, id, 0, tag), "{tag}");
+    }
+    let st = text(&s, id).char_runs()[0].style.clone();
+    assert!(st.ligatures, "liga untouched");
+    assert_eq!((st.size_pt, st.font_family.clone(), st.color), (before.size_pt, before.font_family, before.color));
+}
+
+#[test]
+fn numerals_range_edits_only_those_characters() {
+    let mut s = session(8);
+    let id = text_layer(&mut s, "abcdef");
+    s.execute("type.openType.numerals.lining", json!({"range": [2, 5]})).unwrap();
+    let on: Vec<bool> = (0..6).map(|i| on_at(&s, id, i, "lnum")).collect();
+    assert_eq!(on, [false, false, true, true, true, false]);
+    assert_eq!(numerals_style_at(text(&s, id), 2), Some(NumeralsStyle::Lining));
+    assert_eq!(numerals_style_at(text(&s, id), 0), Some(NumeralsStyle::Default));
+    s.execute("type.openType.numerals.tabular", json!({"range": [2, 5]})).unwrap();
+    assert!(on_at(&s, id, 3, "tnum") && !on_at(&s, id, 3, "lnum"));
+    assert!(!on_at(&s, id, 0, "tnum"));
+}
+
+#[test]
+fn numerals_apply_to_every_listed_layer() {
+    let mut s = session(8);
+    let a = text_layer(&mut s, "one");
+    let b = text_layer(&mut s, "two");
+    s.execute("type.openType.numerals.oldstyle", json!({"layers": [a.0, b.0]})).unwrap();
+    assert!(on_at(&s, a, 0, "onum") && on_at(&s, b, 2, "onum"));
+    s.execute("type.openType.numerals.default", json!({"layers": [a.0, b.0]})).unwrap();
+    assert!(!on_at(&s, a, 0, "onum") && !on_at(&s, b, 0, "onum"));
+}
+
+#[test]
+fn numerals_are_one_undo_step_each() {
+    let mut s = session(8);
+    let id = text_layer(&mut s, "123");
+    s.execute("type.openType.numerals.lining", json!({})).unwrap();
+    s.execute("type.openType.numerals.tabularOldstyle", json!({})).unwrap();
+    assert!(s.undo());
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::Lining));
+    assert!(s.undo());
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::Default));
+    assert!(s.redo());
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::Lining));
+}
+
+#[test]
+fn numerals_survive_a_pcraft_round_trip() {
+    let mut s = session(8);
+    let id = text_layer(&mut s, "Il36");
+    s.execute("type.openType.numerals.proportionalLining", json!({})).unwrap();
+    let bytes = photocraft_format::save_to_bytes(&s.active().unwrap().doc, &Default::default()).unwrap();
+    let doc = photocraft_format::load_from_bytes(&bytes).unwrap();
+    let Some(LayerContent::Text(t)) = doc.layer(id).map(|l| &l.content) else { panic!("text layer lost") };
+    assert_eq!(numerals_style_of(&t.char_runs()[0].style), Some(NumeralsStyle::ProportionalLining));
+}
+
+#[test]
+fn numerals_fail_gracefully_on_bad_params() {
+    let mut s = session(8);
+    let bg = s.active().unwrap().active_layer.unwrap();
+    let id = text_layer(&mut s, "abc");
+    let cmd = "type.openType.numerals.tabularLining";
+    assert!(s.execute(cmd, json!({"layer": 987_654})).is_err(), "unknown layer");
+    assert!(s.execute(cmd, json!({"layer": bg.0})).is_err(), "not a type layer");
+    assert!(s.execute(cmd, json!({"layers": ["x"]})).is_err());
+    s.execute(cmd, json!({"range": [5, 2]})).unwrap();
+    s.execute(cmd, json!({"range": [50, 90]})).unwrap();
+    s.execute(cmd, json!({"range": [u64::MAX, 0]})).unwrap();
+    s.execute(cmd, json!({"range": "all"})).unwrap();
+    assert!(s.execute(cmd, json!({"layer": id.0, "range": [0, 1]})).is_ok());
+    assert_eq!(numerals_style_of(&text(&s, id).char_runs()[0].style), Some(NumeralsStyle::TabularLining));
+}
+
+#[test]
+fn numerals_tabular_changes_inter_digit_widths() {
+    let mut s = session(8);
+    let r = s.execute("type.create", json!({"x": 20, "y": 70, "text": "1111111111", "font": "Inter", "size": 36, "color": "#000000"})).unwrap();
+    let id = LayerId(r["layer"].as_u64().unwrap());
+    let width = |s: &Session| {
+        let t = text(s, id).clone();
+        let mut e = photocraft_text::shared().lock().unwrap_or_else(|e| e.into_inner());
+        let layout = e.layout(&t, 72.0);
+        layout.lines.first().map_or(0.0, |line| line.x1 - line.x0)
+    };
+    let plain = width(&s);
+    s.execute("type.openType.numerals.tabular", json!({})).unwrap();
+    let tab = width(&s);
+    assert!((tab - plain).abs() > 0.5, "tnum changes Inter's digit advances: {plain} → {tab}");
+    s.execute("type.openType.numerals.default", json!({})).unwrap();
+    assert!((width(&s) - plain).abs() < 0.5, "default restores the advances");
+}
+
 #[test]
 fn lorem_update_fonts_and_default_styles() {
     let mut s = session(16);
diff --git a/crates/text/src/tests.rs b/crates/text/src/tests.rs
index 3aa0e6d40f..b88ec9ec72 100644
--- a/crates/text/src/tests.rs
+++ b/crates/text/src/tests.rs
@@ -1732,6 +1732,26 @@ fn psd_round_trips_antialias_opentype_and_warp() {
     }
 }
 
+/// EngineData only maps Photoshop's `OldStyle` bool to `onum`. Other Numerals tags (`lnum` /
+/// `pnum` / `tnum`) stay in `.pcraft` until a Photoshop-authored PSD oracle exists — we do not
+/// invent EngineData keys or copy figure-style tables from GPL editors (AGENTS.md clean-room).
+#[test]
+fn psd_engine_data_keeps_only_oldstyle_among_numeral_tags() {
+    let style = CharStyle {
+        font_family: "Inter".into(),
+        size_pt: 20.0,
+        features: ["lnum", "onum", "pnum", "tnum"].iter().map(|t| FontFeature { tag: (*t).into(), value: 1 }).collect(),
+        ..Default::default()
+    };
+    let t = styled("0123456789", style);
+    let bytes = crate::psd::build_tysh(&t, 72.0, None);
+    let back = crate::psd::text_layer_from_tysh(&bytes, 72.0).expect("tysh");
+    let runs = back.char_runs();
+    let mut got: Vec<&str> = runs[0].style.features.iter().map(|f| f.tag.as_str()).collect();
+    got.sort_unstable();
+    assert_eq!(got, ["onum"]);
+}
+
 /// A legacy-signature `TySh` (#1469): zero PointBase, `bounds` (the layout box) and `boundingBox`
 /// (the ink box, as Photoshop writes it) both around `anchor` in a remote local space, and a
 /// `transform` that cancels the remote origin.
diff --git a/crates/ui-egui/src/menu_catalog.rs b/crates/ui-egui/src/menu_catalog.rs
index 1d98028625..09f732dc7a 100644
--- a/crates/ui-egui/src/menu_catalog.rs
+++ b/crates/ui-egui/src/menu_catalog.rs
@@ -474,6 +474,15 @@ pub static CATALOG: &[(&[&str], &str, Option<&str>, &str)] = &[
     (&["Type", "OpenType"], "Ornaments", None, "type.openType.ornaments"),
     (&["Type", "OpenType"], "Ordinals", None, "type.openType.ordinals"),
     (&["Type", "OpenType"], "Fractions", None, "type.openType.fractions"),
+    (&["Type", "OpenType", "Numerals"], "Default", None, "type.openType.numerals.default"),
+    (&["Type", "OpenType", "Numerals"], "Lining", None, "type.openType.numerals.lining"),
+    (&["Type", "OpenType", "Numerals"], "Oldstyle", None, "type.openType.numerals.oldstyle"),
+    (&["Type", "OpenType", "Numerals"], "Proportional", None, "type.openType.numerals.proportional"),
+    (&["Type", "OpenType", "Numerals"], "Tabular", None, "type.openType.numerals.tabular"),
+    (&["Type", "OpenType", "Numerals"], "Proportional Lining", None, "type.openType.numerals.proportionalLining"),
+    (&["Type", "OpenType", "Numerals"], "Tabular Lining", None, "type.openType.numerals.tabularLining"),
+    (&["Type", "OpenType", "Numerals"], "Proportional Oldstyle", None, "type.openType.numerals.proportionalOldstyle"),
+    (&["Type", "OpenType", "Numerals"], "Tabular Oldstyle", None, "type.openType.numerals.tabularOldstyle"),
     (&["Type"], "---", None, "---"),
     (&["Type"], "Create Work Path", None, "type.createWorkPath"),
     (&["Type"], "Convert to Shape", None, "type.convertToShape"),
diff --git a/crates/ui-egui/src/menus/parity.rs b/crates/ui-egui/src/menus/parity.rs
index ab5fd5eee7..2aa25e9b40 100644
--- a/crates/ui-egui/src/menus/parity.rs
+++ b/crates/ui-egui/src/menus/parity.rs
@@ -7,7 +7,7 @@ use crate::menu_catalog::CATALOG;
 use crate::menus::is_live;
 
 /// Minimum number of live catalog items. Raise it when parity grows; never lower it.
-pub const FLOOR: usize = 631;
+pub const FLOOR: usize = 640;
 
 /// One top-level menu's coverage.
 #[derive(Clone, Debug, serde::Serialize)]
diff --git a/crates/ui-egui/src/menus/view_cmds/dispatch.rs b/crates/ui-egui/src/menus/view_cmds/dispatch.rs
index 80e8d41c88..d103ef5f14 100644
--- a/crates/ui-egui/src/menus/view_cmds/dispatch.rs
+++ b/crates/ui-egui/src/menus/view_cmds/dispatch.rs
@@ -185,6 +185,13 @@ fn type_checked(app: &PhotocraftApp, id: &str) -> Option<bool> {
         return Some(t.is_some_and(|t| (t.orientation == photocraft_doc::text::Orientation::Vertical) == (k == "vertical")));
     }
     let t = t?;
+    // The style where the menu reads: the selection start while editing a range (as the Character
+    // panel shows it), else the layer's first run.
+    let start = crate::type_tool::target(app).and_then(|(_, range)| range).map_or(0, |r| r[0]);
+    if let Some(key) = id.strip_prefix("type.openType.numerals.") {
+        let want = photocraft_engine::type_extra_cmds::NumeralsStyle::from_id(key)?;
+        return Some(photocraft_engine::type_extra_cmds::numerals_style_at(t, start) == Some(want));
+    }
     let tag = match id.strip_prefix("type.openType.")? {
         "standardLigatures" => "liga",
         "contextualAlternates" => "calt",
@@ -198,7 +205,7 @@ fn type_checked(app: &PhotocraftApp, id: &str) -> Option<bool> {
         "fractions" => "frac",
         _ => return None,
     };
-    Some(t.char_runs().first().is_some_and(|r| photocraft_engine::type_extra_cmds::feature_on(&r.style, tag)))
+    Some(photocraft_engine::type_extra_cmds::feature_on_at(t, start, tag))
 }
 
 /// Engine commands that get a dialog or file picker here when invoked without parameters.
diff --git a/crates/ui-egui/src/menus/view_cmds/tests.rs b/crates/ui-egui/src/menus/view_cmds/tests.rs
index 3ef2ab13fa..a8928891ad 100644
--- a/crates/ui-egui/src/menus/view_cmds/tests.rs
+++ b/crates/ui-egui/src/menus/view_cmds/tests.rs
@@ -255,6 +255,26 @@ fn type_menu_checkmarks_follow_the_layer() {
     assert_eq!(checked(&app, "type.orientation.horizontal"), Some(true));
 }
 
+#[test]
+fn numerals_checkmark_follows_the_selection() {
+    let (mut app, ctx) = app_with(1);
+    let id = "type.openType.numerals.tabularLining";
+    assert!(!crate::menus::is_enabled(&app, id));
+    assert_eq!(checked(&app, id), None, "no type layer");
+    app.run("type.create", json!({"x": 10, "y": 50, "text": "Type", "size": 24})).unwrap();
+    assert!(crate::menus::is_enabled(&app, id));
+    assert_eq!(checked(&app, "type.openType.numerals.default"), Some(true));
+    assert_eq!(checked(&app, id), Some(false));
+    menu(&mut app, &ctx, id, json!({})).unwrap();
+    assert_eq!(checked(&app, id), Some(true));
+    assert_eq!(checked(&app, "type.openType.numerals.default"), Some(false));
+    assert_eq!(checked(&app, "type.openType.numerals.lining"), Some(false));
+    menu(&mut app, &ctx, "type.openType.numerals.default", json!({})).unwrap();
+    assert_eq!(checked(&app, "type.openType.numerals.default"), Some(true));
+    assert_eq!(checked(&app, id), Some(false));
+    assert_eq!(checked(&app, "type.openType.numerals.notAStyle"), None);
+}
+
 #[test]
 fn batch_menu_requires_a_recorded_action() {
     let (mut app, ctx) = app_with(1);
diff --git a/docs/gaps.md b/docs/gaps.md
index 0b7ee59a00..2460f2e34c 100644
--- a/docs/gaps.md
+++ b/docs/gaps.md
@@ -99,8 +99,10 @@ what an agent can't finish alone.
   and saves back into the file's `Txt2` since 2026-10-21, #7962),
   the visual RTL caret and PSD storage of the paragraph direction (TYPE-218-2; the paragraph
   direction buttons landed 2026-10-22), complex-script fallback fonts and golden tests
-  (TYPE-218-3), OpenType Numerals and Stylistic Sets submenus
-  (TYPE-218-5; the Character panel buttons landed 2026-10-11, #3752), text free transform
+  (TYPE-218-3), OpenType Stylistic Sets submenu and greying out features the font lacks
+  (TYPE-218-5; Character panel buttons 2026-10-11, #3752; Numerals submenu 2026-11-03 —
+  `.pcraft` keeps all figure tags; PSD EngineData only `OldStyle`/`onum` until a Photoshop-authored
+  oracle lands), text free transform
   (#2630), area type in PSD (TYPE-218-10). Done since the re-measure: manual and optical kerning with PSD round trip
   (TYPE-218-6, #206), variable-font axes (TYPE-218-4, #2985), Warp on live type without a
   rasterize prompt, as in Photoshop (TYPE-218-9, #3004), and the live Warp Text preview that opens
@@ -528,6 +530,7 @@ what an agent can't finish alone.
 | 2026-10-11 | minor | G13: Czech dynamic UI text localized; engine messages and native review remain open |
 | 2026-10-11 | minor | G8: triple/quadruple/five-click type selection done (TYPE-218-8, #3493); Type evidence recounted |
 | 2026-10-11 | minor | G4: Pattern Stamp and Background Eraser draw live, Spot Healing shows a dark overlay while dragging (#3754); only the Mixer Brush is left of TOOL-213-7 |
+| 2026-11-03 | minor | G8: Type › OpenType › Numerals submenu landed (TYPE-218-5); `.pcraft` keeps figure tags, PSD only `OldStyle`/`onum` for now; Stylistic Sets and font-feature greying still missing |
 | 2026-10-11 | minor | G8: Character panel OpenType buttons landed (TYPE-218-5, #3752); Numerals and Stylistic Sets submenus still missing |
 | 2026-10-11 | minor | G10: one-page flattened PDF write shipped (io::pdf, #3401); FILE-215-10 now partial |
 | 2026-10-10 | minor | G2: recorded Tilt-Shift computation/filtered-proxy measurements and limits; gap and estimate remain open
diff --git a/docs/parity-checklist.md b/docs/parity-checklist.md
index 5c747e5d52..064be8aba2 100644
--- a/docs/parity-checklist.md
+++ b/docs/parity-checklist.md
@@ -2,7 +2,7 @@
 
 Generated by `cargo xtask parity` from `crates/ui-egui/src/menu_catalog.rs` (Photoshop's menu tree) and the live command registry. Do not edit by hand.
 
-**631 of 631 menu items live (100.0%).**
+**640 of 640 menu items live (100.0%).**
 
 | Menu | Live | Total | % |
 |---|---:|---:|---:|
@@ -10,7 +10,7 @@ Generated by `cargo xtask parity` from `crates/ui-egui/src/menu_catalog.rs` (Pho
 | Edit | 75 | 75 | 100% |
 | Image | 61 | 61 | 100% |
 | Layer | 163 | 163 | 100% |
-| Type | 45 | 45 | 100% |
+| Type | 54 | 54 | 100% |
 | Select | 25 | 25 | 100% |
 | Filter | 75 | 75 | 100% |
 | View | 74 | 74 | 100% |
diff --git a/docs/scorecard.md b/docs/scorecard.md
index 884db18142..813312df90 100644
--- a/docs/scorecard.md
+++ b/docs/scorecard.md
@@ -11,7 +11,7 @@ Generated by `cargo xtask scorecard` from `perf/budgets.toml`, `perf/baseline.js
 | [Tools](#tools) | 36 | 9 | 0 |  |
 | [Workspace and UI](#workspace-and-ui) | 15 | 6 | 2 | settings that do nothing: 10 of 186 (target 0) |
 | [Type](#type) | 5 | 5 | 0 |  |
-| [Automation](#automation) | 5 | 2 | 4 | 631 of 631 menu items live (100.0%) |
+| [Automation](#automation) | 5 | 2 | 4 | 640 of 640 menu items live (100.0%) |
 | [Reliability](#reliability) | 5 | 2 | 0 | never-crash lints on 30 of 30 crates; panic_hunt present |
 | [Distribution](#distribution) | 5 | 5 | 1 |  |
 | [Open bugs](#open-bugs) | 31 | 1 | 0 |  |
@@ -241,7 +241,7 @@ Unread: `general.color_picker`, `workspace.auto_show_hidden_panels`, `workspace.
 | TYPE-218-2 | Paragraph direction (Auto/LTR/RTL) in the panel and options bar; visual RTL caret | partial | [#218](https://github.com/storytold/photocraft/issues/218) | Paragraph section (Window > Paragraph and Properties) and the options bar have Auto / Left-to-right / Right-to-left buttons setting the paragraph direction through type.setStyle; the options bar's choice is also the direction new type starts with (type_tool.rs direction_items; paragraph_direction_buttons_set_and_show_the_direction, options_bar_direction_sets_selected_layers_and_new_type). Still missing: visual RTL caret (the arrow keys move in logical order), and PSD doesn't store the direction (crates/text psd.rs neither reads nor writes it, so it reopens as Auto) |
 | TYPE-218-3 | Thai/Khmer/Indic fallback fonts; golden shaping tests for complex scripts and RTL | partial | [#218](https://github.com/storytold/photocraft/issues/218) | Fallback fonts are covered for Thai, Khmer, Lao, Myanmar (THAI_FAMILIES, KHMER_FAMILIES, LAO_FAMILIES, MYANMAR_FAMILIES in fonts.rs; #1909, #3259), the nine Indic scripts (INDIC_FAMILIES: Nirmala UI, Kohinoor and Sangam MN, Noto Sans) and Arabic and Hebrew. Still missing: per-script golden shaping tests against reference output (only smoke tests that an installed font shapes without .notdef, plus a bidi test) |
 | TYPE-218-4 | Variable font axis sliders from the font's axes; opsz follows the point size | done | [#218](https://github.com/storytold/photocraft/issues/218) | One slider per axis of the style's font in the Character section (Properties and Window > Character), setting type.setStyle variations; opsz follows the type size unless set (layout.rs variation_list); a style or weight resets the wght axis (#2985). PSD does not round-trip axis values yet |
-| TYPE-218-5 | OpenType UI: Character panel buttons, Numerals and Stylistic Sets submenus | partial | [#218](https://github.com/storytold/photocraft/issues/218) | Type > OpenType toggles (type_extra_cmds.rs:512). Character panel (and the Properties Character section) has Photoshop's eight OpenType buttons: Standard Ligatures, Contextual Alternates, Discretionary Ligatures, Swash, Stylistic Alternates, Titling Alternates, Ordinals, Fractions, pressed while the feature is on at the selection and dispatching the type.openType.* commands (type_tool.rs opentype_row; character_panel_opentype_buttons_toggle_and_show_the_feature, #3752). Still missing: the Numerals and Stylistic Sets submenus, and greying out features the font lacks |
+| TYPE-218-5 | OpenType UI: Character panel buttons, Numerals and Stylistic Sets submenus | partial | [#218](https://github.com/storytold/photocraft/issues/218) | Type > OpenType toggles (type_extra_cmds.rs). Character panel (and the Properties Character section) has Photoshop's eight OpenType buttons: Standard Ligatures, Contextual Alternates, Discretionary Ligatures, Swash, Stylistic Alternates, Titling Alternates, Ordinals, Fractions, pressed while the feature is on at the selection and dispatching the type.openType.* commands (type_tool.rs opentype_row; character_panel_opentype_buttons_toggle_and_show_the_feature, #3752). Type > OpenType > Numerals (Default, Lining, Oldstyle, Proportional, Tabular, and the four height×width combinations) landed 2026-11-03: each sets lnum/onum/pnum/tnum as a radio style on the selection or layer, round-trips .pcraft, and shows its checkmark from the style at the selection start. Still missing: the Stylistic Sets submenu, and greying out features the font lacks |
 | TYPE-218-6 | Manual pair kerning (Alt+arrows), optical kerning rendered, both round-trip PSD (#206) | done | [#218](https://github.com/storytold/photocraft/issues/218) | Alt+Left/Right at a collapsed caret kerns the pair (type_tool.rs kern_pair, 20 per step and 100 with Cmd; type_tool_alt_arrows_kern_the_pair). Optical kerning is computed from the glyph outlines in text/src/optical.rs and applied by layout.rs when the run's mode is Optical (optical_matches_photoshop, optical_kerning_tightens_open_pairs). Both modes and manual values round-trip through PSD (io/tests/it/psd_kerning.rs; the optical mode travels in Txt2, txt2_carries_optical_kerning) |
 | TYPE-218-7 | Warp Text dialog previews live and opens with the layer's current warp | done | [#218](https://github.com/storytold/photocraft/issues/218) | Type > Warp Text opens with the shown layer's warp, or None, never remembered values (filter_dialog.rs:503 warp_defaults; warp_text_dialog_tests.rs:80 warp_text_opens_with_the_type_layers_current_warp, :99 warp_text_opens_at_none_for_a_layer_without_warp, :108 remembered_warp_values_never_override_the_layers_warp). The dialog previews live without editing the document, Cancel leaves no step and OK is one undoable step (:138 warp_text_dialog_previews_the_warp_without_editing_the_document, :160 cancelling_warp_text_leaves_the_document_and_history_untouched, :179 confirming_warp_text_is_one_undoable_step); the reduced-proxy preview matches the full-size result (filter_dialog.rs:2150 warp_text_preview_matches_the_full_size_result_on_a_reduced_proxy) |
 | TYPE-218-8 | Text editing: select all, double/triple/quadruple-click selection, paste, with tests | done | [#218](https://github.com/storytold/photocraft/issues/218) | Like Photoshop, 2 clicks select the word, 3 the laid-out line (a column in vertical type), 4 the paragraph up to the hard return, 5 all text, and the next quick click starts over (#3493; type_tool.rs next_click_count, click_selection, multi_click). Tested through real canvas clicks in point, paragraph and vertical type, with paste replacing the selection and Cmd+A selecting all (type_tool_tests.rs multi_click_selects_word_line_paragraph_and_all_in_point_text, multi_click_separates_wrapped_lines_from_paragraphs, click_counts_cycle_and_restart, click_selection_without_layout_and_on_hostile_input, multi_click_without_a_session_does_nothing) |
@@ -250,7 +250,7 @@ Unread: `general.color_picker`, `workspace.auto_show_hidden_panels`, `workspace.
 
 ## Automation
 
-Menu wiring (`docs/parity-checklist.md`): 631 of 631 menu items live (100.0%). This counts dispatch, not behaviour.
+Menu wiring (`docs/parity-checklist.md`): 640 of 640 menu items live (100.0%). This counts dispatch, not behaviour.
 
 | Id | Target | Status | Issue | Note |
 |---|---|---|---|---|
diff --git a/scorecard/type.toml b/scorecard/type.toml
index c119ac984d..24e5afe709 100644
--- a/scorecard/type.toml
+++ b/scorecard/type.toml
@@ -37,7 +37,7 @@ id = "TYPE-218-5"
 target = "OpenType UI: Character panel buttons, Numerals and Stylistic Sets submenus"
 status = "partial"
 issue = 218
-note = "Type > OpenType toggles (type_extra_cmds.rs:512). Character panel (and the Properties Character section) has Photoshop's eight OpenType buttons: Standard Ligatures, Contextual Alternates, Discretionary Ligatures, Swash, Stylistic Alternates, Titling Alternates, Ordinals, Fractions, pressed while the feature is on at the selection and dispatching the type.openType.* commands (type_tool.rs opentype_row; character_panel_opentype_buttons_toggle_and_show_the_feature, #3752). Still missing: the Numerals and Stylistic Sets submenus, and greying out features the font lacks"
+note = "Type > OpenType toggles (type_extra_cmds.rs). Character panel (and the Properties Character section) has Photoshop's eight OpenType buttons: Standard Ligatures, Contextual Alternates, Discretionary Ligatures, Swash, Stylistic Alternates, Titling Alternates, Ordinals, Fractions, pressed while the feature is on at the selection and dispatching the type.openType.* commands (type_tool.rs opentype_row; character_panel_opentype_buttons_toggle_and_show_the_feature, #3752). Type > OpenType > Numerals (Default, Lining, Oldstyle, Proportional, Tabular, and the four height×width combinations) landed 2026-11-03: each sets lnum/onum/pnum/tnum as a radio style on the selection or layer, round-trips .pcraft, and shows its checkmark from the style at the selection start. Still missing: the Stylistic Sets submenu, and greying out features the font lacks"
 
 [[item]]
 id = "TYPE-218-6"

From d9dc644db145f218836f021713efdb9d5dcde12b Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 17:55:42 +0100
Subject: [PATCH 107/109] fix(ui): Roundness previews its radius within 1 px,
 and a held frame survives a factor change (#10474) (#11081)

* fix(ui): Roundness previews its radius within 1 px too, and a held frame survives a factor change (#10474)

Follow-up to #10524 from its last CodeRabbit review.

- Roundness's disc reaches floor(r) pixels along an axis, so at 6 px
  and k = 4 the proxy radius 1.5 reached 1 proxy px: a 4 px preview for
  a 6 px result. The factor now keeps floor(r / k) * k within 1 px of
  floor(r), as Squareness already does with round (k = 3 at 6 px, k = 2
  at 50 px). One whole-pixel function per mode replaces the special case.
- A canvas test drives the worker across a factor change: the frame for
  k = 2 stays on the canvas, at its own size, until the k = 1 frame lands.

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

* test(ui): a fractional Roundness radius previews closer at its chosen factor (#10474)

CodeRabbit on #11081: only the factors were pinned. At 6.5 px the
Roundness preview at the chosen k = 3 is compared with OK's result and
must differ less than the k = 4 preview did.

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

* fix(ui): a mid-drag frame for the previous proxy factor still reaches the canvas (#10474)

CodeRabbit on #11081: the display gate keeps a held frame at any factor,
but the mid-drag publish arm still required the same factor, so a frame
finished for the factor the drag just left was dropped. It now uses
same_target_at_any_scale too; a frame already exact for the dialog is
still never displaced.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/canvas/filter_preview.rs   | 11 +++++---
 crates/ui-egui/src/canvas/tests.rs            | 25 +++++++++++++++++++
 crates/ui-egui/src/dialogs/filter_dialog.rs   |  9 ++++---
 .../src/dialogs/filter_dialog/tests.rs        | 21 +++++++++++++---
 4 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/crates/ui-egui/src/canvas/filter_preview.rs b/crates/ui-egui/src/canvas/filter_preview.rs
index 0144390b46..3a6ee54d97 100644
--- a/crates/ui-egui/src/canvas/filter_preview.rs
+++ b/crates/ui-egui/src/canvas/filter_preview.rs
@@ -84,11 +84,14 @@ pub(crate) fn ensure_filter_preview(app: &mut PhotocraftApp, idx: usize, ctx: &e
                 Ok(computed) if finished == request => publish_filter_preview(app, idx, finished, computed.result, computed.ms),
                 // Mid-drag, a frame for the value the pointer has just left is what makes the
                 // canvas follow the drag. Three things have to hold for it: it belongs to this
-                // preview, it has a frame to show (an empty one would blank a good preview), and
-                // it must not displace a frame that is already exact for the dialog, which is
-                // what a slider dragged out and back would otherwise make the canvas do.
+                // preview (at any proxy factor: it is drawn at its own, and a radius drag can move
+                // the factor, #10474), it has a frame to show (an empty one would blank a good
+                // preview), and it must not displace a frame that is already exact for the dialog,
+                // which is what a slider dragged out and back would otherwise make the canvas do.
                 Ok(computed)
-                    if finished.same_target(&request) && computed.result.is_some() && !app.filter_preview.as_ref().is_some_and(|p| p.key == request) =>
+                    if finished.same_target_at_any_scale(&request)
+                        && computed.result.is_some()
+                        && !app.filter_preview.as_ref().is_some_and(|p| p.key == request) =>
                 {
                     publish_filter_preview(app, idx, finished, computed.result, computed.ms);
                 }
diff --git a/crates/ui-egui/src/canvas/tests.rs b/crates/ui-egui/src/canvas/tests.rs
index 6bce89cc0d..73ef696976 100644
--- a/crates/ui-egui/src/canvas/tests.rs
+++ b/crates/ui-egui/src/canvas/tests.rs
@@ -371,6 +371,31 @@ fn drive_until(app: &mut PhotocraftApp, ctx: &egui::Context, what: &str, done: i
     }
 }
 
+#[cfg(not(target_arch = "wasm32"))]
+#[test]
+fn a_held_preview_frame_stays_on_the_canvas_when_the_proxy_factor_changes() {
+    // #10474: Minimum and Maximum take their proxy factor from the radius, so a radius drag across
+    // a whole pixel changes `FilterPreviewKey::k`. The frame for the old factor stays on the
+    // canvas, drawn at its own factor, until the one for the new factor lands.
+    let mut app = PhotocraftApp::new(photocraft_engine::Session::new(), Default::default());
+    app.run("file.new", json!({"width": 2400, "height": 2200})).unwrap();
+    app.background_jobs = true;
+    app.ui.views.get_mut(0).expect("the new document's view").zoom = 0.25;
+    crate::filter_dialog::open(&mut app, "filter.other.maximum").unwrap();
+    app.ui.dialogs[0].fields.insert("radius".into(), json!(6.0));
+    let ctx = egui::Context::default();
+    drive_until(&mut app, &ctx, "the first frame", |a| a.filter_preview.as_ref().is_some_and(|p| p.result.is_some()));
+    assert_eq!(app.filter_preview.as_ref().map(|p| p.key.k), Some(2), "6 px on a reduced document previews on the proxy");
+
+    // 1.5 px previews at full resolution: a new request at a new factor, computed on the worker.
+    app.ui.dialogs[0].fields.insert("radius".into(), json!(1.5));
+    let (k, _, size) = ensure_filter_preview(&mut app, 0, &ctx).expect("the held frame stays on the canvas");
+    assert_eq!((k, size), (2, [1200, 1100]), "drawn at its own factor");
+    drive_until(&mut app, &ctx, "the full-resolution frame", |a| a.filter_preview.as_ref().is_some_and(|p| p.key.k == 1 && p.result.is_some()));
+    let (k, _, size) = ensure_filter_preview(&mut app, 0, &ctx).expect("the new frame");
+    assert_eq!((k, size), (1, [2400, 2200]));
+}
+
 #[cfg(not(target_arch = "wasm32"))]
 #[test]
 fn a_preview_computed_mid_drag_reaches_the_canvas_and_then_converges() {
diff --git a/crates/ui-egui/src/dialogs/filter_dialog.rs b/crates/ui-egui/src/dialogs/filter_dialog.rs
index 08ce0f6ab1..f2e97a80e8 100644
--- a/crates/ui-egui/src/dialogs/filter_dialog.rs
+++ b/crates/ui-egui/src/dialogs/filter_dialog.rs
@@ -279,16 +279,17 @@ pub fn preview_factor(command: &str, params: &Value, k: u32) -> u32 {
     // Minimum and Maximum measure the radius in whole pixels (Squareness rounds it, Roundness
     // floors it, and 0 is the identity), so at k = 4 a typed 1.5 px became 0.375 = 0 proxy px and
     // the preview showed the untouched document while OK applied a real effect (#10474). Keep at
-    // least one proxy pixel of radius, and for Squareness the largest k whose rounded proxy radius,
-    // scaled back, is within 1 px of the one OK applies (6 px at k = 4 rounded to 2 proxy px, 8 px).
+    // least one proxy pixel of radius, and the largest k whose whole-pixel proxy radius, scaled
+    // back, is within 1 px of the one OK applies: Squareness at 6 px and k = 4 rounds 1.5 to 2 proxy
+    // px (8 px), and Roundness's disc reaches floor(1.5) = 1 proxy px along an axis (4 px).
     // A large radius still previews on a proxy: at full size Roundness costs O(radius) per pixel.
     if matches!(command, "filter.other.minimum" | "filter.other.maximum") {
         let Some(r) = params.get("radius").and_then(Value::as_f64).filter(|r| r.is_finite()) else { return k };
         let r = r.clamp(0.2, 500.0);
-        let square = params.get("preserve").and_then(Value::as_str) != Some("roundness");
+        let whole: fn(f64) -> f64 = if params.get("preserve").and_then(Value::as_str) == Some("roundness") { f64::floor } else { f64::round };
         let fits = |d: u32| {
             let d = f64::from(d);
-            d <= r.floor() && (!square || ((r / d).round() * d - r.round()).abs() <= 1.0)
+            d <= r.floor() && (whole(r / d) * d - whole(r)).abs() <= 1.0
         };
         return (1..=k).rev().find(|&d| fits(d)).unwrap_or(1);
     }
diff --git a/crates/ui-egui/src/dialogs/filter_dialog/tests.rs b/crates/ui-egui/src/dialogs/filter_dialog/tests.rs
index c5013adc25..dcaa32ddbd 100644
--- a/crates/ui-egui/src/dialogs/filter_dialog/tests.rs
+++ b/crates/ui-egui/src/dialogs/filter_dialog/tests.rs
@@ -1047,16 +1047,29 @@ fn proxy_previews_scale_only_lengths() {
     assert_eq!(preview_factor("filter.pixelate.mosaic", &json!({"cellSize": "x"}), 4), 4);
     let (k, diff) = error("filter.pixelate.mosaic", json!({"cellSize": 10.0}));
     assert!(k == 2 && diff < 0.01, "Mosaic: {diff}");
+    // Roundness at a fractional radius: at 6.5 px, k = 3 reaches floor(2.17) = 2 proxy px along an
+    // axis (6 px), where k = 4 reached floor(1.63) = 1 (4 px), so the chosen factor previews closer
+    // to what OK applies than k = 4 did (#10474).
+    for cmd in ["filter.other.minimum", "filter.other.maximum"] {
+        let p = json!({"radius": 6.5, "preserve": "roundness"});
+        let (k, diff) = error(cmd, p.clone());
+        let applied = preview_document(&doc, Some(bg), cmd, &p, 1).unwrap();
+        let at_four = preview_document(&doc, Some(bg), cmd, &p, 4).unwrap();
+        let four = mean_abs(&every_kth(&applied, 4), &every_kth(&at_four, 1));
+        assert!(k == 3 && diff < four, "{cmd}: k = {k} differs by {diff}, k = 4 by {four}");
+    }
     // Minimum and Maximum keep at least one proxy pixel of radius (#10474), and a large radius
-    // keeps a proxy instead of a full-size preview that costs minutes at radius 500. Squareness
-    // also keeps its rounded radius within 1 px of OK's: 6 px is 2 proxy px at k = 3 (6 px), not
-    // at k = 4 (8 px); 50 px is 17 at k = 3 (51 px), not 13 at k = 4 (52 px).
+    // keeps a proxy instead of a full-size preview that costs minutes at radius 500. Both keep
+    // their whole-pixel radius within 1 px of OK's. Squareness rounds: 6 px is 2 proxy px at k = 3
+    // (6 px), not at k = 4 (8 px); 50 px is 17 at k = 3 (51 px), not 13 at k = 4 (52 px). Roundness's
+    // disc reaches floor(r) along an axis: 6 px is 2 at k = 3 (6 px), not 1 at k = 4 (4 px); 50 px
+    // is 25 at k = 2, not 12 at k = 4 or 16 at k = 3 (48 px).
     let factors = |cmd: &str, preserve: &str| {
         [0.2, 1.5, 2.5, 3.9, 6.0, 50.0, 500.0, 9999.0].map(|radius| preview_factor(cmd, &json!({"radius": radius, "preserve": preserve}), 4))
     };
     for cmd in ["filter.other.minimum", "filter.other.maximum"] {
         assert_eq!(factors(cmd, "squareness"), [1, 1, 2, 3, 3, 3, 4, 4], "{cmd} squareness");
-        assert_eq!(factors(cmd, "roundness"), [1, 1, 2, 3, 4, 4, 4, 4], "{cmd} roundness");
+        assert_eq!(factors(cmd, "roundness"), [1, 1, 2, 3, 3, 2, 4, 4], "{cmd} roundness");
         assert_eq!(preview_factor(cmd, &json!({"radius": 6.0}), 4), 3, "{cmd}: Squareness is the default");
         assert_eq!(preview_factor(cmd, &json!({"radius": "x"}), 4), 4, "{cmd}: a junk radius keeps the proxy");
     }

From d07684a379103df3523ceb4cd5210598303a9415 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 17:55:50 +0100
Subject: [PATCH 108/109] fix(ui): Overscroll off keeps an image smaller than
 the window centred (#10488) (#11085)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ui): Overscroll off keeps an image smaller than the window centred (#10488)

With Tools › Overscroll off, an image smaller than the window stayed
wherever zooming around the pointer left it, inside the window, so
zooming out drifted it off centre. #1718 measured that on Photoshop 25.4,
but two reports of Photoshop itself (#10488, #4799) say it stays centred
with Overscroll off. The owner chose the centred behaviour:
scrollbars::clamp_axis now centres an axis on which the image is no
larger than the view; a larger image still can't leave its edges, and
Overscroll on keeps the free view.

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

* test(ui): Overscroll off centres a fitting rotated image (#10488)

CodeRabbit on #11085: the rotated clamp path was only tested from an
already-centred view. A 600 px square at 45 degrees, started off centre
in a 900-point view, now ends with its screen bounds centred.

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

* style(ui): keep the rotated centring test within rustfmt's width

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/ui-egui/src/canvas/scrollbars.rs | 58 ++++++++++++++++---------
 docs/ui-parity.md                       |  1 +
 2 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/crates/ui-egui/src/canvas/scrollbars.rs b/crates/ui-egui/src/canvas/scrollbars.rs
index 375edc13b6..305e9c86d3 100644
--- a/crates/ui-egui/src/canvas/scrollbars.rs
+++ b/crates/ui-egui/src/canvas/scrollbars.rs
@@ -71,9 +71,13 @@ impl Span {
     }
 }
 
-/// Clamp one axis of the view centre with Overscroll off, as Photoshop 25.4 does: an image larger
-/// than the view can't leave its edges, and one smaller than the view stays inside it, where
-/// zooming put it (zooming out around the pointer doesn't re-centre it; Fit on Screen does).
+/// Clamp one axis of the view centre with Overscroll off: an image larger than the view can't
+/// leave its edges, and one smaller than the view is centred in it, so zooming out around the
+/// pointer keeps it in the middle (#10488, #4799).
+///
+/// #1718 measured Photoshop 25.4 leaving a smaller image where zooming put it. Two reports of
+/// Photoshop itself say it stays centred with Overscroll off, which is what turning Overscroll off
+/// is asked for, so PhotoCraft centres it; Overscroll on keeps the free view.
 pub fn clamp_axis(center: f32, len: f32, size: f32, zoom: f32) -> f32 {
     if !(zoom.is_finite() && zoom > 0.0 && len.is_finite() && len > 0.0 && size.is_finite() && size > 0.0) {
         return center;
@@ -82,9 +86,11 @@ pub fn clamp_axis(center: f32, len: f32, size: f32, zoom: f32) -> f32 {
         return len / 2.0;
     }
     let half = size / zoom / 2.0;
-    // Larger: the view stays within the image. Smaller: the image stays within the view.
-    let (a, b) = (half, len - half);
-    center.clamp(a.min(b), a.max(b))
+    // Smaller than the view (or exactly its size): centred. Larger: the view stays within it.
+    if 2.0 * half >= len {
+        return len / 2.0;
+    }
+    center.clamp(half, len - half)
 }
 
 /// Apply Preferences › Tools › Overscroll (off) to `view` for a canvas of `size` points on a
@@ -112,7 +118,7 @@ pub fn clamp_view_with_aspect(view: &mut View, size: egui::Vec2, ppp: f32, aspec
             if view.center[0].is_finite() { view.center[0] } else { w as f32 / 2.0 },
             if view.center[1].is_finite() { view.center[1] } else { h as f32 / 2.0 },
         ];
-        let xf = crate::canvas::ViewXform { rect: egui::Rect::from_min_size(Pos2::ZERO, size), zoom, center, flip: false, rotation: view.rotation, aspect };
+        let xf = crate::canvas::ViewXform { rect: Rect::from_min_size(Pos2::ZERO, size), zoom, center, flip: false, rotation: view.rotation, aspect };
         let image = xf.image_bounds(view.doc_size);
         if !image.is_finite() {
             return false;
@@ -309,12 +315,13 @@ mod tests {
         assert_eq!(clamp_axis(-400.0, 1000.0, 500.0, 1.0), 250.0);
         assert_eq!(clamp_axis(4000.0, 1000.0, 500.0, 1.0), 750.0);
         assert_eq!(clamp_axis(600.0, 1000.0, 500.0, 1.0), 600.0);
-        // Smaller than the view (2500 doc px of view for 1000 of image): it stays where it is
-        // while it is inside the view, and is pushed back in at the edges.
-        assert_eq!(clamp_axis(-90.0, 1000.0, 500.0, 0.2), -90.0);
-        assert_eq!(clamp_axis(-400.0, 1000.0, 500.0, 0.2), -250.0, "the image's right edge on the view's");
-        assert_eq!(clamp_axis(1400.0, 1000.0, 500.0, 0.2), 1250.0, "its left edge on the view's");
+        // Smaller than the view (2500 doc px of view for 1000 of image): centred, wherever zooming
+        // around the pointer left it (#10488).
+        for center in [-90.0, -400.0, 300.0, 1400.0] {
+            assert_eq!(clamp_axis(center, 1000.0, 500.0, 0.2), 500.0, "{center}");
+        }
         assert_eq!(clamp_axis(500.0, 1000.0, 1000.0, 1.0), 500.0, "exactly the view's size: centred");
+        assert_eq!(clamp_axis(10.0, 1000.0, 1000.0, 1.0), 500.0);
         let mut v = View {
             zoom: 1.0,
             center: [-500.0, 20.0],
@@ -332,6 +339,20 @@ mod tests {
         assert!(!clamp_view(&mut v, vec2(500.0, 400.0), 1.0), "stable: no repaint loop");
     }
 
+    #[test]
+    fn overscroll_off_centres_a_fitting_rotated_image() {
+        // 600 px at 45 degrees is about 849 points across, so it fits a 900-point view both ways.
+        // Started off centre, the clamp centres its screen-space bounds in the view (#10488).
+        let mut v = View { zoom: 1.0, center: [100.0, 450.0], doc_size: [600, 600], rotation: 45.0, ..Default::default() };
+        let size = vec2(900.0, 900.0);
+        assert!(clamp_view_with_aspect(&mut v, size, 1.0, 1.0));
+        let rect = Rect::from_min_size(Pos2::ZERO, size);
+        let xf = crate::canvas::ViewXform { rect, zoom: 1.0, center: v.center, flip: false, rotation: v.rotation, aspect: 1.0 };
+        let c = xf.image_bounds(v.doc_size).center();
+        assert!((c - xf.rect.center()).length() < 1e-2, "centred: {c:?}");
+        assert!(!clamp_view_with_aspect(&mut v, size, 1.0, 1.0), "stable: no repaint loop");
+    }
+
     #[test]
     fn hostile_numbers_are_harmless() {
         for z in [0.0, -1.0, f32::NAN, f32::INFINITY] {
@@ -516,16 +537,13 @@ mod tests {
                 } else {
                     assert!((x - w / 2.0).abs() < 1e-3, "clamped to the left edge: {x}");
                 }
-                // Zoomed out below fit (Photoshop): the image is not re-centred, it stays where it
-                // is while it fits in the view, and is pushed back in at the view's edge.
+                // Zoomed out below fit: the image is centred in the view on both axes, wherever
+                // the zoom left it (#10488).
                 set_view(&mut h, 0.1, [-50.0, 9000.0]);
                 if !overscroll {
-                    let r = h.state().last_canvas_rect;
-                    let (hw, hh) = (r.width() / 0.1 / 2.0, r.height() / 0.1 / 2.0);
-                    let c = view(&h).center;
-                    assert_eq!(c[0], -50.0, "inside the view: left alone");
-                    assert!((c[1] - hh).abs() < 1e-2, "pushed back in: the image's top on the view's: {c:?}");
-                    assert!(c[0] - hw <= 0.0 && c[0] + hw >= 2000.0 && c[1] - hh <= 0.0 && c[1] + hh >= 1500.0, "{c:?}");
+                    assert_eq!(view(&h).center, [1000.0, 750.0], "centred");
+                } else {
+                    assert_eq!(view(&h).center, [-50.0, 9000.0], "overscroll on: the view is free");
                 }
             }
         }
diff --git a/docs/ui-parity.md b/docs/ui-parity.md
index 07192e710f..3dbec47b9f 100644
--- a/docs/ui-parity.md
+++ b/docs/ui-parity.md
@@ -350,4 +350,5 @@ Paragraph; the rest open as in-app floating windows.
 | 2026-10-15 | minor | ⇧⌥ blend mode letters work while a Free Transform box is open, without picking a tool |
 | 2026-10-14 | minor | Mode dropdowns for Clone Stamp, Pattern Stamp, History Brush, Healing and Paint Bucket; the blend mode keys reach them, and tools without a blend mode (not Dodge, Burn or Sponge) pass the keys to the layers |
 | 2026-10-16 | minor | Hand tool: ⌘ held zooms in and ⌥ zooms out, as in Photoshop (#6434) |
+| 2026-11-03 | minor | Tools › Overscroll off centres an image smaller than the window on that axis, so zooming out around the pointer keeps it in the middle instead of where the zoom left it (#10488, #4799); this overrides #1718's Photoshop 25.4 measurement on the strength of two Photoshop users' reports, and Overscroll on keeps the free view; no percentage changed |
 | 2026-10-31 | minor | Ctrl + Alt + wheel over the canvas zooms like ⌥ + wheel (#10488): ×1.1 a notch around the pointer with Animated Zoom off, eased with it on, and it follows the ⌥ swap when General › Zoom with Scroll Wheel is on. Windows and Linux report a held Ctrl as ctrl AND command (`wheel_nav::alt_gesture`), macOS ⌘ + ⌥ is left alone, plain ⌘/Ctrl + wheel still scrolls sideways; the combination was a dead gesture, so nothing existing was replaced. The centred-zoom half of the report is still open: `canvas.rs:1737` re-clamps the view centre each frame only when Tools › Overscroll is off (it is on by default), so the drift the reporter saw is more likely the deliberate nearest-image-point anchor (`view_xform.rs:239`, #3720) or Zoom Clicked Point to Center, which needs its own repro; no percentage changed |

From 996a52cb8fc920f3b5883dd8d77d42bfa18d1302 Mon Sep 17 00:00:00 2001
From: FredApps <153173854+FredApps@users.noreply.github.com>
Date: Tue, 3 Nov 2026 18:00:23 +0100
Subject: [PATCH 109/109] PSD export: a cancelled save stops between the bands
 of a banded layer

A banded layer checks the save's interrupt before each band and before each
channel's part of a band. Once cancelled it stops there and doesn't encode the
layer again raw; the incomplete model is discarded by the caller (which returns
IoError::Cancelled), so the save never reaches its commit point and the target
is untouched. Ex carries the export's Interrupt for this.

Addresses CodeRabbit review on crates/io/src/psd_export/banded.rs.
---
 crates/io/src/psd_export.rs          |  7 +++--
 crates/io/src/psd_export/banded.rs   | 22 ++++++++++++--
 crates/io/src/psd_export/document.rs |  7 +++--
 crates/io/src/psd_export/tests.rs    | 43 ++++++++++++++++++++++++++++
 4 files changed, 72 insertions(+), 7 deletions(-)

diff --git a/crates/io/src/psd_export.rs b/crates/io/src/psd_export.rs
index a98cb347b1..89bf250b4e 100644
--- a/crates/io/src/psd_export.rs
+++ b/crates/io/src/psd_export.rs
@@ -94,7 +94,10 @@ impl Default for PsdExportOptions {
     }
 }
 
-struct Ex {
+struct Ex<'c> {
+    /// The save's interrupt: a layer saved in bands checks it between bands and channels, so a
+    /// cancelled save stops within a band (#5333).
+    ctl: Interrupt<'c>,
     fmt: PixelFormat,
     /// Document resolution (for generated type-layer data).
     dpi: f32,
@@ -181,7 +184,7 @@ fn q255(v: f32) -> u8 {
     (v.clamp(0.0, 1.0) * 255.0).round() as u8
 }
 
-impl Ex {
+impl Ex<'_> {
     fn compression(&self) -> Compression {
         if self.fmt.sample == SampleType::F32 { Compression::ZipPrediction } else { Compression::Rle }
     }
diff --git a/crates/io/src/psd_export/banded.rs b/crates/io/src/psd_export/banded.rs
index f2fc0a7751..a2aed97473 100644
--- a/crates/io/src/psd_export/banded.rs
+++ b/crates/io/src/psd_export/banded.rs
@@ -8,6 +8,10 @@
 //! writes. ZIP with prediction (32-bit) predicts per row and feeds one zlib stream: the same
 //! pixels, but not always the same bytes, as zlib packs input it is given in parts differently.
 //! With a stage each band's parts go to the scratch disk as they are made (see [`Parts`]).
+//!
+//! A banded layer is minutes of work on a large save, so it checks the save's interrupt before
+//! each band and each channel's part of it: once cancelled it stops there (and doesn't retry
+//! raw), leaving an incomplete model that the caller discards before the save's commit point.
 
 use std::io::Write as _;
 
@@ -30,6 +34,8 @@ const BAND_BYTES: usize = 64 << 20;
 thread_local! {
     /// `(BANDED_FROM, BAND_BYTES)` for this thread's exports, so tests band small layers.
     pub(crate) static BANDS_FOR_TESTS: std::cell::Cell<Option<(u64, usize)>> = const { std::cell::Cell::new(None) };
+    /// Bands this thread has gathered and encoded.
+    pub(crate) static BANDS_DONE: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
 }
 
 pub(super) fn banded_from() -> u64 {
@@ -56,12 +62,18 @@ struct Channel {
     parts: Parts,
 }
 
-impl Ex {
+impl Ex<'_> {
     /// The channels of `s` over `r` (non-empty), alpha first, encoded band by band.
     pub(super) fn banded_channels(&self, s: &Surface, r: photocraft_geom::Rect) -> Vec<ChannelData> {
         // RLE fails only on a row too long for its count (not within PSD/PSB limits); then the
         // layer is written raw, as a channel encoded whole falls back to.
-        self.banded_pass(s, r, self.compression()).or_else(|_| self.banded_pass(s, r, Compression::Raw)).unwrap_or_else(|_| self.empty_channels())
+        match self.banded_pass(s, r, self.compression()) {
+            Ok(channels) => channels,
+            // Cancelled: the caller sees the interrupt and discards the whole model, so don't
+            // encode the layer again.
+            Err(_) if self.ctl.cancelled() => self.empty_channels(),
+            Err(_) => self.banded_pass(s, r, Compression::Raw).unwrap_or_else(|_| self.empty_channels()),
+        }
     }
 
     fn banded_pass(&self, s: &Surface, r: photocraft_geom::Rect, compression: Compression) -> photocraft_psd::Result<Vec<ChannelData>> {
@@ -81,7 +93,10 @@ impl Ex {
             .collect();
         let mut invert = vec![self.cmyk; self.cc];
         invert.push(false);
+        let ctl = self.ctl;
+        let check = || if ctl.cancelled() { Err(PsdError::Invalid("cancelled".into())) } else { Ok(()) };
         for y in (0..h).step_by(band_rows) {
+            check()?;
             let rows = band_rows.min(h - y);
             let top = r.y0 + y as i32;
             let pieces = crate::pixels::par_map(crate::pixels::bands(rows), |b| {
@@ -101,6 +116,7 @@ impl Ex {
             let work: Vec<(&mut Channel, Vec<u8>)> =
                 channels.iter_mut().enumerate().map(|(k, c)| (c, planes[if k == 0 { self.cc } else { k - 1 }].take().unwrap_or_default())).collect();
             let done = crate::pixels::par_map(work, |(c, mut plane)| -> photocraft_psd::Result<()> {
+                check()?;
                 match compression {
                     Compression::Rle => {
                         let mut packed = encode_planes(Compression::Rle, &plane, &layout)?;
@@ -120,6 +136,8 @@ impl Ex {
                 Ok(())
             });
             done.into_iter().collect::<photocraft_psd::Result<()>>()?;
+            #[cfg(test)]
+            BANDS_DONE.set(BANDS_DONE.get() + 1);
         }
         channels
             .into_iter()
diff --git a/crates/io/src/psd_export/document.rs b/crates/io/src/psd_export/document.rs
index a87ed93010..b46a21fc3c 100644
--- a/crates/io/src/psd_export/document.rs
+++ b/crates/io/src/psd_export/document.rs
@@ -67,6 +67,7 @@ fn export_supported_document(
     let big = doc.size.width > 30_000 || doc.size.height > 30_000;
     let version = psd_version(doc, opts.force_psb);
     let mut ex = Ex {
+        ctl: *ctl,
         fmt,
         dpi: doc.resolution_dpi,
         document: opts.document_path.clone(),
@@ -311,7 +312,7 @@ struct MergedExport<'a> {
 
 fn prepare_merged_planes<'a>(
     doc: &'a Document,
-    ex: &mut Ex,
+    ex: &mut Ex<'_>,
     opts: &PsdExportOptions,
     ctl: &Interrupt,
     fmt: PixelFormat,
@@ -345,7 +346,7 @@ fn prepare_merged_planes<'a>(
 
 fn append_extra_channels<'a>(
     doc: &'a Document,
-    ex: &mut Ex,
+    ex: &mut Ex<'_>,
     planes: &mut Vec<u8>,
     has_alpha: bool,
     sample: SampleType,
@@ -395,7 +396,7 @@ fn merged_image(doc: &Document, opts: &PsdExportOptions, ctl: &Interrupt, fmt: &
     (planes, has_alpha)
 }
 
-fn index_layer_ids_and_text(doc: &Document, ex: &mut Ex) {
+fn index_layer_ids_and_text(doc: &Document, ex: &mut Ex<'_>) {
     // Assign layer ids up front (stable across round trips): keep unique
     // `psd_id`s, number the rest after them; dividers come after all.
     {
diff --git a/crates/io/src/psd_export/tests.rs b/crates/io/src/psd_export/tests.rs
index c1d47c4777..fdf0288c9d 100644
--- a/crates/io/src/psd_export/tests.rs
+++ b/crates/io/src/psd_export/tests.rs
@@ -799,3 +799,46 @@ fn banded_layers_round_trip() {
     stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
     let _ = std::fs::remove_dir_all(&dir);
 }
+
+/// #5333: a save cancelled while a layer is saved in bands stops at the next band (it neither
+/// finishes the layer nor encodes it again raw) and reports the cancel, so it never reaches its
+/// commit point and the target is never written: RLE and ZIP, PSD and PSB, in memory and staged.
+#[test]
+fn a_cancelled_save_stops_between_the_bands_of_a_layer() {
+    let dir = std::env::temp_dir().join(format!("pc-psd-banded-cancel-{}", std::process::id()));
+    let this = std::thread::current().id();
+    // Cancelled once two bands are done (they are counted on this thread).
+    let after_two = || std::thread::current().id() == this && banded::BANDS_DONE.get() >= 2;
+    let ctl = Interrupt::cancel_only(&after_two);
+    for depth in [SampleType::U8, SampleType::F32] {
+        let doc = banding_document(ColorMode::Rgb, depth, 203, 157);
+        let row_bytes = doc.size.width as usize * doc.pixel_format().bytes_per_pixel();
+        let bands = |ctl: &Interrupt, run: &dyn Fn(&Interrupt)| {
+            banded::BANDS_DONE.set(0);
+            banded::BANDS_FOR_TESTS.set(Some((0, row_bytes + 3)));
+            run(ctl);
+            banded::BANDS_FOR_TESTS.set(None);
+            banded::BANDS_DONE.get()
+        };
+        for force_psb in [false, true] {
+            for staged in [false, true] {
+                let what = format!("{depth:?}, psb {force_psb}, staged {staged}");
+                stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = staged.then(|| dir.clone()));
+                let options = PsdExportOptions { force_psb, stage_on_scratch_from: staged.then_some(0), ..Default::default() };
+                let export = |ctl: &Interrupt| drop(document_to_psd_sized(&doc, &options, 0, ctl, PSD_MAX_FILE_SIZE));
+                let rows = doc.layers[0].surface().unwrap().content_bounds().height() as usize;
+                assert_eq!(bands(&Interrupt::NONE, &export), rows, "{what}: one band a row");
+                assert_eq!(bands(&ctl, &export), 2, "{what}: stops at the band after the cancel");
+            }
+        }
+        stage::DIR_FOR_TESTS.with(|d| *d.borrow_mut() = None);
+        // The save sees the cancel, so it returns before its commit point and writes nothing.
+        let name = format!("banded-cancel-{depth:?}.psd");
+        let save = |ctl: &Interrupt| {
+            let r = crate::encode_with(&doc, &name, &crate::ExportOptions::default(), ctl);
+            assert!(matches!(r, Err(crate::IoError::Cancelled)), "{depth:?}: {:?}", r.err());
+        };
+        assert_eq!(bands(&ctl, &save), 2, "{depth:?}: the save stops at the band after the cancel");
+    }
+    let _ = std::fs::remove_dir_all(&dir);
+}