Plug-ins: filters keep their settings in the document's foreign data (G17)

crates/doc/src/lib.rs

@@ -44,6 +44,7 @@ pub mod perspective;
 mod pixels;
 pub use pixels::MAX_RASTER_ALLOC;
 pub mod placed_document;
+pub mod plugin_data;
 pub mod profiles;
 pub mod puppet;
 pub mod range;

crates/doc/src/plugin_data.rs

@@ -0,0 +1,86 @@
+//! What plug-ins keep with a document: settings that belong to the whole document rather than to
+//! one object, such as the pens a plotter holds or a machine's profile.
+//!
+//! They are the document's foreign data ([`Document::unknown`], under [`PLUGIN_DATA`]), as the
+//! perspective grid and the brushes are, so the native file has no section of its own for them
+//! and a version from before them keeps them when it saves. The host never reads them: a filter
+//! plug-in writes its own and reads only its own back, and an exporter, which is given the whole
+//! document, can read them all (`vectorcraft-plugins`, which caps what one plug-in keeps).
+
+use serde_json::{Map, Value};
+
+use crate::Document;
+
+/// `Document::unknown` key: `{"<plug-in id>": <what it keeps>}`.
+pub const PLUGIN_DATA: &str = "pluginData";
+
+impl Document {
+    /// What plug-in `id` keeps with the document, if anything.
+    pub fn plugin_data(&self, id: &str) -> Option<&Value> {
+        self.unknown.get(PLUGIN_DATA).and_then(|m| m.get(id))
+    }
+
+    /// Keeps `data` for plug-in `id` in place of what it kept; `None` forgets it, and the key goes
+    /// once no plug-in keeps anything. A value under the key that isn't a map of plug-in ids (a
+    /// damaged file) is replaced when a plug-in keeps something.
+    pub fn set_plugin_data(&mut self, id: &str, data: Option<Value>) {
+        let Some(data) = data else {
+            // Nothing to forget: don't copy the foreign data the undo history shares.
+            if self.plugin_data(id).is_none() {
+                return;
+            }
+            let Some(m) = self.unknown.get_mut(PLUGIN_DATA).and_then(Value::as_object_mut) else { return };
+            m.remove(id);
+            if m.is_empty() {
+                self.unknown.remove(PLUGIN_DATA);
+            }
+            return;
+        };
+        let kept = self.unknown.entry(PLUGIN_DATA.to_string()).or_insert_with(|| Value::Object(Map::new()));
+        if !kept.is_object() {
+            *kept = Value::Object(Map::new());
+        }
+        if let Some(m) = kept.as_object_mut() {
+            m.insert(id.to_string(), data);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    /// Each plug-in has its own entry, replaced when it keeps something else; forgetting the last
+    /// one removes the key, and forgetting what isn't kept copies nothing.
+    #[test]
+    fn each_plug_in_keeps_its_own_data() {
+        let mut d = Document::new(10.0, 10.0);
+        assert_eq!(d.plugin_data("a"), None);
+        d.set_plugin_data("a", Some(json!({"pens": 2})));
+        d.set_plugin_data("b", Some(json!([1, 2])));
+        d.set_plugin_data("a", Some(json!({"pens": 3})));
+        assert_eq!((d.plugin_data("a"), d.plugin_data("b")), (Some(&json!({"pens": 3})), Some(&json!([1, 2]))));
+        d.set_plugin_data("a", None);
+        assert_eq!(d.unknown[PLUGIN_DATA], json!({"b": [1, 2]}));
+        let before = d.clone();
+        d.set_plugin_data("a", None);
+        assert!(crate::Shared::ptr_eq(&before.unknown, &d.unknown), "still shared with the earlier version");
+        d.set_plugin_data("b", None);
+        assert!(!d.unknown.contains_key(PLUGIN_DATA));
+    }
+
+    /// A damaged file's value under the key holds nothing for any plug-in, stays while there is
+    /// nothing to forget, and is replaced when a plug-in keeps something.
+    #[test]
+    fn a_damaged_value_holds_nothing() {
+        let mut d = Document::new(10.0, 10.0);
+        d.unknown.insert(PLUGIN_DATA.into(), json!(5));
+        assert_eq!(d.plugin_data("a"), None);
+        d.set_plugin_data("a", None);
+        assert_eq!(d.unknown[PLUGIN_DATA], json!(5));
+        d.set_plugin_data("a", Some(json!(true)));
+        assert_eq!(d.unknown[PLUGIN_DATA], json!({"a": true}));
+    }
+}

crates/engine/src/cmd/plugin.rs

@@ -4,9 +4,10 @@
 //! [`Session::attach_plugin_store`]) or from every `*.wasm` in the Additional Plug-ins Folder
 //! preference, and listed with `plugin.list` / `plugin.info`. Object filters run
 //! with `plugin.run` on the selected paths and compound paths (one undo step, transactional: a
-//! plug-in that fails leaves the document untouched); live-effect plug-ins are applied like any
-//! effect (`effect.apply {effect: "plugin.<id>"}`) and drawn by `vectorcraft-effects`; exporters
-//! add a file format that `document.export` writes (`fileio::plugin_formats`).
+//! plug-in that fails leaves the document untouched), and read and write the data they keep with
+//! the document ([`vectorcraft_doc::plugin_data`], theirs alone); live-effect plug-ins are applied
+//! like any effect (`effect.apply {effect: "plugin.<id>"}`) and drawn by `vectorcraft-effects`;
+//! exporters add a file format that `document.export` writes (`fileio::plugin_formats`).
 
 use std::sync::{Arc, Mutex};
 
@@ -60,8 +61,9 @@ fn plugin_by_id(cmd: &str, p: &Value) -> Result<Arc<Plugin>> {
 }
 
 /// `plugin.run`: runs filter `id` on `ids` (else the selected paths and compound paths) with its
-/// parameters and `_context`, and applies its output as one undo step ([`objects::apply_output`];
-/// effect records as [`admit_effects`] admits them). → `{plugin, ids}`: what it made or changed,
+/// parameters and `_context` (what it keeps with the document included), and applies its output as
+/// one undo step ([`objects::apply_output`]; effect records as [`admit_effects`] admits them),
+/// with what it keeps with the document from now on. → `{plugin, ids}`: what it made or changed,
 /// which is then selected.
 fn run(s: &mut Session, p: &Value) -> Result<Value> {
     const C: &str = "plugin.run";
@@ -85,12 +87,17 @@ fn run(s: &mut Session, p: &Value) -> Result<Value> {
     let bounds = st.doc.bounds_of(&inputs, false);
     let board = bounds.and_then(|b| st.doc.artboard_at(b.center())).and_then(|i| st.doc.artboards.get(i)).or(st.doc.artboards.first());
     let rect = |r: vectorcraft_geom::Rect| json!([r.x0, r.y0, r.x1, r.y1]);
-    params["_context"] = json!({"mode": "filter", "bounds": bounds.map(rect), "artboard": board.map(|a| rect(a.rect))});
+    // What the plug-in keeps with the document, as it last wrote it.
+    let data = st.doc.plugin_data(&m.id).cloned().unwrap_or(Value::Null);
+    params["_context"] = json!({"mode": "filter", "bounds": bounds.map(rect), "artboard": board.map(|a| rect(a.rect)), "documentData": data});
     let input = objects::encode_input(&st.doc, &inputs);
     let params = serde_json::to_vec(&params).map_err(|e| bad(C, e.to_string()))?;
-    let out = objects::decode(&plugin.run(&input, &params).map_err(err)?).map_err(err)?;
+    let out = objects::decode_output(&plugin.run(&input, &params).map_err(err)?).map_err(err)?;
     let ids = s.edit(m.name.trim_end_matches('…'), |d, sel| {
-        let ids = objects::apply_output(d, &inputs, out, parent, &admit_effects).map_err(err)?;
+        let ids = objects::apply_output(d, &inputs, out.objects, parent, &admit_effects).map_err(err)?;
+        if let Some(data) = out.document_data {
+            d.set_plugin_data(&m.id, data);
+        }
         sel.set(ids.iter().copied());
         Ok(ids)
     })?;

crates/engine/src/tests_plugins.rs

@@ -330,6 +330,53 @@ fn rough_frame_test_filter() {
     std::fs::write(std::path::Path::new(&dir).join("rough-frame-test-filter.wasm"), wat::parse_str(src).unwrap()).unwrap();
 }
 
+/// A filter keeps data with the document: it writes it with `documentData` in the same undo step as
+/// its objects (`null` removes it) and reads what it last wrote in `_context.documentData`, which
+/// no other filter is given. It is the document's foreign data, so the native file keeps it with
+/// no section of its own. More than the limit is refused.
+#[test]
+fn filters_keep_their_data_with_the_document() {
+    let mut s = session();
+    let id = rect(&mut s, 10.0, "#ff0000");
+    let pid = "test.engine.data";
+    let returning = |out: Value| tpl::returning(&tpl::manifest(pid, "filter", "{}"), &out.to_string());
+    let keep = |data: Value| json!({"objects": [{"id": id.0}], "documentData": data});
+    let data = |s: &Session| s.doc().unwrap().doc.plugin_data(pid).cloned();
+    let filter = |s: &mut Session, pid: &str| s.execute("plugin.run", &json!({"id": pid, "ids": [id.0]}));
+    install_wat(&mut s, &returning(keep(json!({"pen": 2}))));
+    filter(&mut s, pid).unwrap();
+    assert_eq!(data(&s), Some(json!({"pen": 2})));
+    run(&mut s, "edit.undo", json!({}));
+    assert_eq!(data(&s), None, "one undo step with the objects");
+    run(&mut s, "edit.redo", json!({}));
+    // Read back: these name the object only when they are given what they look for.
+    let named = |name: &str| json!({"objects": [{"id": id.0, "name": name}]}).to_string();
+    let when_given =
+        |pid: &str, needle: &str, name: &str| tpl::when_given(&tpl::manifest(pid, "filter", "{}"), tpl::Given::Params, needle, &named(name));
+    install_wat(&mut s, &when_given(pid, r#""documentData":{"pen":2}"#, "Pen 2"));
+    filter(&mut s, pid).unwrap();
+    assert_eq!(node(&s, id).name.as_deref(), Some("Pen 2"));
+    // Another filter is given nothing: what a filter keeps is its own.
+    let other = "test.engine.other";
+    install_wat(&mut s, &when_given(other, r#""documentData":null"#, "Nothing kept"));
+    filter(&mut s, other).unwrap();
+    assert_eq!(node(&s, id).name.as_deref(), Some("Nothing kept"));
+    // Saved with the document, among its foreign data.
+    let saved = vectorcraft_format::load(&vectorcraft_format::save(&s.doc().unwrap().doc, false)).unwrap();
+    assert_eq!(saved.plugin_data(pid), Some(&json!({"pen": 2})));
+    assert_eq!(saved.unknown.get(vectorcraft_doc::plugin_data::PLUGIN_DATA), Some(&json!({pid: {"pen": 2}})));
+    // Too much is refused, and the document stays as it was; null removes the data.
+    let before = s.doc().unwrap().doc.clone();
+    let big = "x".repeat(vectorcraft_plugins::objects::MAX_DOCUMENT_DATA);
+    install_wat(&mut s, &returning(keep(json!(big))));
+    let e = filter(&mut s, pid).unwrap_err().to_string();
+    assert!(e.contains("documentData"), "{e}");
+    assert_eq!(s.doc().unwrap().doc, before);
+    install_wat(&mut s, &returning(keep(Value::Null)));
+    filter(&mut s, pid).unwrap();
+    assert_eq!(data(&s), None);
+}
+
 #[test]
 fn plugin_management_commands() {
     let mut s = session();

crates/engine/tests/plugin_export.rs

@@ -104,6 +104,23 @@ fn the_exporter_is_given_the_native_file_s_json() {
     assert!(image.get("blob").is_some() && image.get("data").is_none(), "{image}");
 }
 
+/// What filter plug-ins keep with the document reaches an exporter with the rest of the document:
+/// a plotter's exporter finds the pens a setup filter kept (`document.unknown.pluginData`, by
+/// plug-in id).
+#[test]
+fn an_exporter_finds_what_filters_keep_with_the_document() {
+    let mut s = session();
+    s.execute("select.none", &json!({})).unwrap();
+    let pens = json!({"pens": [{"slot": 1, "width": 0.3}, {"slot": 2, "width": 0.5}]});
+    let setup = json!({"objects": [], "documentData": pens});
+    install(&mut s, &tpl::returning(&tpl::manifest("test.setup", "filter", "{}"), &setup.to_string()));
+    s.execute("plugin.run", &json!({"id": "test.setup"})).unwrap();
+    install(&mut s, &tpl::echo_exporter(&tpl::exporter("test.pens", r#"["tsd"]"#, "{}"), Echo::Input));
+    let r = s.execute("document.export", &json!({"format": "plugin.test.pens"})).unwrap();
+    let doc: Value = serde_json::from_slice(&exported(&r)).unwrap();
+    assert_eq!(doc["document"]["unknown"][vectorcraft_doc::plugin_data::PLUGIN_DATA], json!({"test.setup": pens}));
+}
+
 #[test]
 fn the_exporter_is_given_its_parameters_and_the_file_it_writes() {
     let dir = tmp_dir("params");

crates/plugins/src/objects.rs

@@ -30,6 +30,8 @@ pub const MAX_STROKE_WIDTH: f64 = 1000.0;
 pub const MITER_LIMIT: std::ops::RangeInclusive<f64> = 1.0..=500.0;
 /// Longest effect id a plug-in may return, in bytes.
 pub const MAX_EFFECT_ID: usize = 128;
+/// Largest data a plug-in may keep with a document (`documentData`), in bytes of JSON.
+pub const MAX_DOCUMENT_DATA: usize = 1 << 20;
 
 /// One object returned by a plug-in. `None` fields keep the object's value (new objects take the
 /// defaults: a path, non-zero rule, no fills or strokes, full opacity).
@@ -373,11 +375,45 @@ fn decode_effect(v: &Value, at: &str) -> Result<Effect> {
     Ok(Effect { id: id.to_string(), params, visible })
 }
 
-/// Parses a plug-in's output: `{"objects": [...]}`, or `{"error": "message"}` when the plug-in
-/// declined (the message reaches the user).
+/// What a filter returned: its objects, and what it keeps with the document.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Output {
+    pub objects: Vec<OutObject>,
+    /// `documentData`, as `Document::set_plugin_data` takes it: `None` when the output has none
+    /// (what the plug-in keeps stays as it is), `Some(None)` for `null` (it forgets it), else what
+    /// it keeps from now on, at most [`MAX_DOCUMENT_DATA`] bytes of JSON.
+    pub document_data: Option<Option<Value>>,
+}
+
+/// Parses a filter's output: `{"objects": [...], "documentData"?: …}`, or `{"error": "message"}`
+/// when the plug-in declined (the message reaches the user).
+pub fn decode_output(bytes: &[u8]) -> Result<Output> {
+    let mut v: Value = serde_json::from_slice(bytes).map_err(|e| Error::Output(format!("not JSON: {e}")))?;
+    let objects = decode_objects(&v)?;
+    let document_data = match v.get_mut("documentData").map(Value::take) {
+        None => None,
+        Some(Value::Null) => Some(None),
+        Some(data) => {
+            let size = serde_json::to_vec(&data).map_or(usize::MAX, |b| b.len());
+            if size > MAX_DOCUMENT_DATA {
+                return Err(Error::Output(format!("`documentData` is {size} bytes (limit {MAX_DOCUMENT_DATA})")));
+            }
+            Some(Some(data))
+        }
+    };
+    Ok(Output { objects, document_data })
+}
+
+/// Parses a plug-in's objects: `{"objects": [...]}`, or `{"error": "message"}` when the plug-in
+/// declined (the message reaches the user). A live effect's other keys don't matter.
 pub fn decode(bytes: &[u8]) -> Result<Vec<OutObject>> {
     let v: Value = serde_json::from_slice(bytes).map_err(|e| Error::Output(format!("not JSON: {e}")))?;
-    if let Some(e) = declined(&v) {
+    decode_objects(&v)
+}
+
+/// The objects of output `v`, or its decline.
+fn decode_objects(v: &Value) -> Result<Vec<OutObject>> {
+    if let Some(e) = declined(v) {
         return Err(e);
     }
     let objects = v.get("objects").and_then(Value::as_array).ok_or_else(|| Error::Output("expected {\"objects\": [...]}".into()))?;

crates/plugins/src/objects/tests.rs

@@ -269,3 +269,25 @@ fn bad_stroke_styles_and_effect_records_are_refused() {
         assert!(decode_json(json!({"objects": [{"id": a, "effects": bad}]})).is_err(), "{bad}");
     }
 }
+
+/// A filter's `documentData`: absent keeps what the plug-in keeps, `null` forgets it, any other JSON
+/// of at most [`MAX_DOCUMENT_DATA`] bytes is kept, and more refuses the whole output.
+#[test]
+fn document_data_is_kept_forgotten_or_refused() {
+    let out = |data: Option<Value>| {
+        let mut v = json!({"objects": []});
+        if let Some(data) = data {
+            v["documentData"] = data;
+        }
+        decode_output(v.to_string().as_bytes()).map(|o| o.document_data)
+    };
+    assert_eq!(out(None).unwrap(), None);
+    assert_eq!(out(Some(Value::Null)).unwrap(), Some(None));
+    assert_eq!(out(Some(json!({"pens": 2}))).unwrap(), Some(Some(json!({"pens": 2}))));
+    // A string's quotes count: this one is the limit exactly, and one more byte refuses it.
+    let at = json!("x".repeat(MAX_DOCUMENT_DATA - 2));
+    assert_eq!(out(Some(at.clone())).unwrap(), Some(Some(at)));
+    assert!(matches!(out(Some(json!("x".repeat(MAX_DOCUMENT_DATA - 1)))), Err(Error::Output(_))));
+    // A decline is still a decline.
+    assert!(matches!(decode_output(br#"{"error": "No pens.", "documentData": 1}"#), Err(Error::Failed(_))));
+}

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

@@ -4627,6 +4627,7 @@ imageTrace	Outline	Obrys
 @msg	{_1} font families available	Dostupné rodiny písem: {_1}
 @msg	{_1} is a live effect (Effect › Plug-ins)	{_1} je živý efekt (Efekt › Zásuvné moduly)
 @msg	{_1} is an exporter (File › Export › Export As…)	{_1} je exportní zásuvný modul (Soubor › Export › Exportovat jako…)
+@msg	`documentData` is {size} bytes (limit {MAX_DOCUMENT_DATA})	`documentData` má {size} bajtů (limit {MAX_DOCUMENT_DATA})
 @msg	{_1} is already used by {_2}	{_1} už používá {_2}
 @msg	{_1} linked file(s) can't be read here: their previews show	propojené soubory ({_1}) zde nelze přečíst: zobrazují se jejich náhledy
 @msg	{_1} linked image(s) changed on disk: Update Links shows the new versions	propojené obrázky ({_1}) se na disku změnily: nové verze zobrazí Aktualizovat propojení

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

@@ -4250,6 +4250,7 @@ theme	Appearance	Erscheinungsbild
 @msg	{_1} font families available	{_1} Schriftfamilien verfügbar
 @msg	{_1} is a live effect (Effect › Plug-ins)	{_1} ist ein Live-Effekt (Effekt › Plug-ins)
 @msg	{_1} is an exporter (File › Export › Export As…)	{_1} ist ein Export-Plug-in (Datei › Exportieren › Exportieren als…)
+@msg	`documentData` is {size} bytes (limit {MAX_DOCUMENT_DATA})	`documentData` ist {size} Byte groß (Grenze {MAX_DOCUMENT_DATA})
 @msg	{_1} is already used by {_2}	{_1} wird bereits von {_2} verwendet
 @msg	{_1} linked file(s) can't be read here: their previews show	{_1} verknüpfte Datei(en) können hier nicht gelesen werden: Ihre Vorschauen werden angezeigt
 @msg	{_1} linked image(s) changed on disk: Update Links shows the new versions	{_1} verknüpfte(s) Bild(er) wurde(n) auf dem Datenträger geändert: „Verknüpfungen aktualisieren“ zeigt die neuen Versionen

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

@@ -4298,6 +4298,7 @@ theme	Appearance	Εμφάνιση
 @msg	{_1} font families available	{_1} διαθέσιμες οικογένειες γραμματοσειρών
 @msg	{_1} is a live effect (Effect › Plug-ins)	το {_1} είναι δυναμικό εφέ (Εφέ › Πρόσθετα)
 @msg	{_1} is an exporter (File › Export › Export As…)	το {_1} είναι πρόσθετο εξαγωγής (Αρχείο › Εξαγωγή › Εξαγωγή ως…)
+@msg	`documentData` is {size} bytes (limit {MAX_DOCUMENT_DATA})	το `documentData` έχει {size} byte (όριο {MAX_DOCUMENT_DATA})
 @msg	{_1} is already used by {_2}	το {_1} χρησιμοποιείται ήδη από το {_2}
 @msg	{_1} linked file(s) can't be read here: their previews show	{_1} συνδεδεμένα αρχεία δεν μπορούν να διαβαστούν εδώ: εμφανίζονται οι προεπισκοπήσεις τους
 @msg	{_1} linked image(s) changed on disk: Update Links shows the new versions	{_1} συνδεδεμένες εικόνες άλλαξαν στον δίσκο: η Ενημέρωση συνδέσμων εμφανίζει τις νέες εκδόσεις

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

@@ -4325,6 +4325,7 @@ axis	Both	Ambos
 @msg	{_1} font families available	{_1} familias de fuentes disponibles
 @msg	{_1} is a live effect (Effect › Plug-ins)	{_1} es un efecto interactivo (Efecto › Plugins)
 @msg	{_1} is an exporter (File › Export › Export As…)	{_1} es un plugin de exportación (Archivo › Exportar › Exportar como…)
+@msg	`documentData` is {size} bytes (limit {MAX_DOCUMENT_DATA})	`documentData` ocupa {size} bytes (límite {MAX_DOCUMENT_DATA})
 @msg	{_1} is already used by {_2}	{_1} ya lo usa {_2}
 @msg	{_1} linked file(s) can't be read here: their previews show	aquí no se pueden leer {_1} archivo(s) vinculado(s): se muestran sus previsualizaciones
 @msg	{_1} linked image(s) changed on disk: Update Links shows the new versions	{_1} imagen(es) vinculada(s) cambiaron en el disco: Actualizar vínculos muestra las versiones nuevas