Add optional snapping to visible mask edges

This commit is contained in:
Dandaedre 2026-11-16 22:53:15 +01:00
parent 2bb23f39a8
commit c334794798
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
32 changed files with 697 additions and 64 deletions

2
Cargo.lock generated
View File

@ -548,7 +548,7 @@ dependencies = [
[[package]]
name = "canvas-pilot"
version = "0.9.12"
version = "0.9.13"
dependencies = [
"base64",
"craft-dwg",

View File

@ -4,7 +4,7 @@ default-members = ["crates/canvas-pilot"]
resolver = "3"
[workspace.package]
version = "0.9.12"
version = "0.9.13"
edition = "2024"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot"

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Mask edges",
"ui.rename-layer": "Rename layer…",
"ui.move-to-folder": "Move to folder",
"ui.no-folder": "No folder",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Randoj de maskoj",
"ui.rename-layer": "Renomi tavolon…",
"ui.move-to-folder": "Movi al dosierujo",
"ui.no-folder": "Sen dosierujo",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Bordes de máscara",
"ui.rename-layer": "Renombrar capa…",
"ui.move-to-folder": "Mover a carpeta",
"ui.no-folder": "Sin carpeta",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Bords des masques",
"ui.rename-layer": "Renommer le calque…",
"ui.move-to-folder": "Déplacer vers un dossier",
"ui.no-folder": "Sans dossier",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Ἄκρα τῶν καλυμμάτων",
"ui.rename-layer": "Μετονόμασον τὸ στρῶμα…",
"ui.move-to-folder": "Εἰς φάκελον μετάθεσον",
"ui.no-folder": "Ἄνευ φακέλου",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "मास्क के किनारे",
"ui.rename-layer": "परत का नाम बदलें…",
"ui.move-to-folder": "फ़ोल्डर में ले जाएँ",
"ui.no-folder": "कोई फ़ोल्डर नहीं",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "マスクの端",
"ui.rename-layer": "レイヤー名を変更…",
"ui.move-to-folder": "フォルダーに移動",
"ui.no-folder": "フォルダーなし",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "मास्कका किनाराहरू",
"ui.rename-layer": "तहको नाम फेर्नुहोस्…",
"ui.move-to-folder": "फोल्डरमा सार्नुहोस्",
"ui.no-folder": "फोल्डर छैन",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "Limites da máscara",
"ui.rename-layer": "Mudar nome da camada…",
"ui.move-to-folder": "Mover para pasta",
"ui.no-folder": "Sem pasta",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "ขอบมาสก์",
"ui.rename-layer": "เปลี่ยนชื่อเลเยอร์…",
"ui.move-to-folder": "ย้ายไปโฟลเดอร์",
"ui.no-folder": "ไม่มีโฟลเดอร์",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "poka pi len sitelen",
"ui.rename-layer": "o ante e nimi lipu…",
"ui.move-to-folder": "o tawa kulupu",
"ui.no-folder": "kulupu ala",

View File

@ -1,4 +1,5 @@
{
"ui.mask-edges": "蒙版边缘",
"ui.rename-layer": "重命名图层…",
"ui.move-to-folder": "移至文件夹",
"ui.no-folder": "无文件夹",

View File

@ -116,6 +116,7 @@ impl Editor {
ui.ctx(),
"ui.includes-contact-between-mirrored-opposite-resizing-layers",
));
ui.checkbox(&mut self.snapping.mask_edges, tr(ui.ctx(), "ui.mask-edges"));
});
ui.weak(tr(
ui.ctx(),
@ -466,6 +467,27 @@ mod tests {
);
frame(app, ctx, vec![mouse(pos, false)]);
}
#[test]
fn mask_snapping_menu_persists_without_editing_geometry() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("settings.json");
let (store, saved) = settings::Store::at(path.clone());
let ctx = egui::Context::default();
let mut app = Editor::with_settings(&ctx, store, saved);
let before = app.layout.layers().clone();
click_label(&mut app, &ctx, "Menu");
click_label(&mut app, &ctx, "Options");
click_label(&mut app, &ctx, "Snapping");
click_label(&mut app, &ctx, "Snap movement & resizing");
click_label(&mut app, &ctx, "Mask edges");
assert!(app.snapping.mask_edges);
assert_eq!(*app.layout.layers(), before);
let (store, saved) = settings::Store::at(path);
assert!(store.error.is_none());
assert!(saved.snapping.mask_edges);
assert!(saved.snapping.enabled);
}
#[test]
fn options_are_saved_and_restored_in_a_fresh_editor() {
let dir = tempfile::tempdir().unwrap();

View File

@ -181,7 +181,7 @@ impl Project {
folders: layout.folders.clone(),
workspace: Workspace::default(),
format: FORMAT.into(),
version: 17,
version: 18,
input_proposals: Vec::new(),
next_layer_id: layout.next_id,
output_resolution: layout.formats.output.into(),
@ -233,9 +233,9 @@ impl Project {
}
/// Build a fresh document only after validating the entire file. No history is restored.
pub fn layout(&self) -> Result<Layout, String> {
if self.format != FORMAT || self.version != 17 {
if self.format != FORMAT || self.version != 18 {
return Err(
"Unsupported project format/version; expected beffroi.midra-layout version 17."
"Unsupported project format/version; expected beffroi.midra-layout version 18."
.into(),
);
}
@ -447,8 +447,8 @@ impl Project {
}
let header: Header =
serde_json::from_str(text).map_err(|e| format!("Invalid project JSON: {e}"))?;
if !(1..=17).contains(&header.version) {
return Err("Unsupported project version; expected versions 1–17.".into());
if !(1..=18).contains(&header.version) {
return Err("Unsupported project version; expected versions 1–18.".into());
}
let mut migrated: serde_json::Value = if header.version == 1 || header.version == 2 {
let mut value: serde_json::Value =
@ -689,6 +689,16 @@ impl Project {
}
migrated["version"] = 17.into();
}
if header.version <= 17 {
let snapping = migrated["workspace"]["snapping"]
.as_object_mut()
.ok_or("Missing snapping")?;
if header.version >= 11 && snapping.contains_key("mask_edges") {
return Err("Unexpected mask_edges in old project.".into());
}
snapping.insert("mask_edges".into(), false.into());
migrated["version"] = 18.into();
}
let p: Self =
serde_json::from_value(migrated).map_err(|e| format!("Invalid project JSON: {e}"))?;
p.layout()?;

View File

@ -24,7 +24,7 @@ pub struct Settings {
impl Default for Settings {
fn default() -> Self {
Self {
version: 13,
version: 14,
ui_scale: 1.0,
text_scale: None,
language: Default::default(),
@ -66,7 +66,7 @@ impl Settings {
}
value["snapping"] = serde_json::to_value(canvas_pilot::snapping::Snapping::default())
.map_err(|e| e.to_string())?;
for field in ["grid", "show_grid", "grid_divisions"] {
for field in ["grid", "show_grid", "grid_divisions", "mask_edges"] {
value["snapping"].as_object_mut().unwrap().remove(field);
}
value["version"] = 3.into();
@ -163,12 +163,25 @@ impl Settings {
if value["version"] == 13 && value.get("text_scale").is_none() {
return Err("Missing text_scale in version 13 settings".into());
}
if value["version"] == 13 {
let snapping = value["snapping"]
.as_object_mut()
.ok_or("Missing snapping")?;
if snapping.contains_key("mask_edges") {
return Err("Unexpected mask_edges in old settings".into());
}
snapping.insert("mask_edges".into(), false.into());
value["version"] = 14.into();
}
if value["version"] == 14 && value.get("text_scale").is_none() {
return Err("Missing text_scale in version 14 settings".into());
}
let settings: Self = serde_json::from_value(value).map_err(|e| e.to_string())?;
settings.validate()?;
Ok(settings)
}
fn validate(&self) -> Result<(), String> {
if self.version != 13 {
if self.version != 14 {
return Err(format!("unsupported settings version {}", self.version));
}
if let crate::localization::Language::Pack(id) = &self.language
@ -310,6 +323,31 @@ impl Store {
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn mask_snapping_migrates_and_requires_current_schema() {
let legacy =
include_str!("../../../docs/interfaces/canvas-pilot-settings-v13.example.json");
let current =
include_str!("../../../docs/interfaces/canvas-pilot-settings-v14.example.json");
assert_eq!(
Settings::parse(legacy).unwrap(),
Settings::parse(current).unwrap()
);
let mut value: serde_json::Value = serde_json::from_str(current).unwrap();
value["snapping"]["mask_edges"] = true.into();
let parsed = Settings::parse(&value.to_string()).unwrap();
assert!(parsed.snapping.mask_edges);
assert_eq!(serde_json::to_value(parsed).unwrap(), value);
value["version"] = 13.into();
assert!(Settings::parse(&value.to_string()).is_err());
value["version"] = 14.into();
value["snapping"]
.as_object_mut()
.unwrap()
.remove("mask_edges");
assert!(Settings::parse(&value.to_string()).is_err());
}
#[test]
fn scaling_migrates_and_round_trips_with_strict_limits() {
let old = include_str!("../../../docs/interfaces/canvas-pilot-settings-v10.example.json");
@ -379,7 +417,7 @@ mod tests {
let old = include_str!("../../../docs/interfaces/canvas-pilot-settings-v8.example.json");
let migrated = Settings::parse(old).unwrap();
assert_eq!(migrated.language, Language::System);
assert_eq!(migrated.version, 13);
assert_eq!(migrated.version, 14);
let current =
include_str!("../../../docs/interfaces/canvas-pilot-settings-v10.example.json");
assert_eq!(Settings::parse(current).unwrap(), migrated);
@ -388,12 +426,13 @@ mod tests {
let mut old: serde_json::Value = serde_json::from_str(v9).unwrap();
old["language"] = old_language.into();
let upgraded = Settings::parse(&old.to_string()).unwrap();
assert_eq!(upgraded.version, 13);
assert_eq!(upgraded.version, 14);
assert_eq!(
serde_json::to_value(&upgraded.language).unwrap(),
old["language"]
);
old["version"] = 13.into();
old["version"] = 14.into();
old["snapping"]["mask_edges"] = false.into();
old["ui_scale"] = serde_json::json!(1.0);
old["text_scale"] = serde_json::Value::Null;
assert_eq!(serde_json::to_value(upgraded).unwrap(), old);
@ -435,6 +474,8 @@ mod tests {
assert!(Settings::parse(&value.to_string()).is_err());
value["version"] = 13.into();
let saved = Settings::parse(&value.to_string()).unwrap();
value["version"] = 14.into();
value["snapping"]["mask_edges"] = false.into();
assert_eq!(serde_json::to_value(saved).unwrap(), value);
for id in ["", "../uk", "uk_UA"] {
value["language"] = serde_json::json!({"pack":id});
@ -469,7 +510,8 @@ mod tests {
value["ui_scale"] = 1.5.into();
value["text_scale"] = 1.25.into();
let saved = Settings::parse(&value.to_string()).unwrap();
value["version"] = 13.into();
value["version"] = 14.into();
value["snapping"]["mask_edges"] = false.into();
assert_eq!(serde_json::to_value(saved).unwrap(), value);
}
}
@ -542,7 +584,7 @@ mod tests {
for text in [
"broken".to_string(),
serde_json::to_string(&Settings {
version: 14,
version: 15,
..Default::default()
})
.unwrap(),

View File

@ -8,6 +8,7 @@ pub struct Snapping {
pub pixels: bool,
pub screen_edges: bool,
pub layer_edges: bool,
pub mask_edges: bool,
pub grid: bool,
pub show_grid: bool,
pub grid_divisions: [u32; 2],
@ -19,6 +20,7 @@ impl Default for Snapping {
pixels: true,
screen_edges: true,
layer_edges: true,
mask_edges: false,
grid: false,
show_grid: true,
grid_divisions: [8, 6],
@ -39,6 +41,66 @@ fn screen_guides(size: u32) -> [f64; 5] {
[0.0, 0.25, 0.5, 0.75, 1.0].map(|fraction| size as f64 * fraction)
}
// Mask fractions are resolved through the same source/layer reference as rendering.
// Clip to the layer aperture; a fully blanked layer has no visible snap edges.
fn mask_geometry(formats: &crate::formats::Formats, index: usize, g: Geometry) -> Option<Geometry> {
let mask = formats.mask_bounds(index, g).ok()?;
let picture = if let Some(fit) = formats.layer_fit[index] {
fit.image(
formats.advanced[index]
.remaining(formats.input(index).ok()?)
.ok()?,
g,
)
.ok()?
} else {
g
};
let x = g.x.max(mask.x).max(picture.x);
let y = g.y.max(mask.y).max(picture.y);
let width = (g.x + g.width)
.min(mask.x + mask.width)
.min(picture.x + picture.width)
- x;
let height = (g.y + g.height)
.min(mask.y + mask.height)
.min(picture.y + picture.height)
- y;
(width > 0.0 && height > 0.0).then_some(Geometry {
x,
y,
width,
height,
})
}
fn edges(g: Geometry, axis: usize) -> [f64; 2] {
if axis == 0 {
[g.x, g.x + g.width]
} else {
[g.y, g.y + g.height]
}
}
impl Snapping {
fn targets(
self,
formats: &crate::formats::Formats,
index: usize,
g: Geometry,
axis: usize,
) -> impl Iterator<Item = f64> {
let mask = self
.mask_edges
.then(|| mask_geometry(formats, index, g))
.flatten();
[self.layer_edges.then_some(g), mask]
.into_iter()
.flatten()
.flat_map(move |g| edges(g, axis))
}
}
impl Layout {
/// Snap a pivot without editing geometry. Local anchors take precedence over
/// grid/edge options; the caller may bypass them for precise free placement.
@ -86,14 +148,10 @@ impl Layout {
if options.grid {
edges.extend(options.grid_guides(self.formats.output[axis], axis));
}
if options.layer_edges {
if options.layer_edges || options.mask_edges {
for (i, other) in self.layers.iter().enumerate() {
if i != index && self.visible(i) {
edges.extend(if axis == 0 {
[other.x, other.x + other.width]
} else {
[other.y, other.y + other.height]
});
edges.extend(options.targets(&self.formats, i, *other, axis));
}
}
}
@ -153,10 +211,10 @@ impl Layout {
Vec::new()
};
targets.extend(grid_targets.iter().copied());
if options.layer_edges {
if options.layer_edges || options.mask_edges {
for (i, g) in before.layers.iter().enumerate() {
if !selected[i] && self.visible[i] {
targets.extend(edge(*g, axis));
targets.extend(options.targets(&before.formats, i, *g, axis));
}
}
}
@ -165,15 +223,20 @@ impl Layout {
if !selected[i] {
continue;
}
for (anchor, moving) in edge(*g, axis)
let mask = options
.mask_edges
.then(|| mask_geometry(&before.formats, i, *g))
.flatten();
for (is_center, moving) in edge(*g, axis)
.into_iter()
.chain(std::iter::once(g.center()[axis]))
.enumerate()
.chain(mask.into_iter().flat_map(|g| edge(g, axis)))
.map(|v| (false, v))
.chain(std::iter::once((true, g.center()[axis])))
{
for target in &targets {
// Centers align to screen interior guides and overlay grid lines;
// other targets retain edge-to-edge behavior.
if anchor == 2
if is_center
&& (!options.screen_edges
|| !screen_guides(self.formats.output[axis])[1..4].contains(target))
&& !grid_targets.contains(target)
@ -317,14 +380,10 @@ impl Layout {
if options.grid {
targets.extend(options.grid_guides(self.formats.output[axis], axis));
}
if options.layer_edges {
if options.layer_edges || options.mask_edges {
for (i, g) in r.before.layers.iter().enumerate() {
if !r.targets[i] && self.visible(i) {
targets.extend(if axis == 0 {
[g.x, g.x + g.width]
} else {
[g.y, g.y + g.height]
});
targets.extend(options.targets(&r.before.formats, i, *g, axis));
}
}
}

View File

@ -240,7 +240,7 @@ fn family_links_save_migrate_recover_and_validate() {
let mut old: Value = serde_json::from_str(old).unwrap();
old["layers"][0]["midra_link"] = json!({"screen":"001","layer":"02"});
let p = Project::from_json(&old.to_string()).unwrap();
assert_eq!(p.version, 17);
assert_eq!(p.version, 18);
assert_eq!(
p.layers[0].device_link.as_ref().unwrap().family,
Family::Midra4k
@ -300,7 +300,7 @@ fn documented_v13_example_contains_native_aquilon_link() {
"../../../docs/interfaces/canvas-pilot-v13.example.json"
))
.unwrap();
assert_eq!(p.version, 17);
assert_eq!(p.version, 18);
let link = p.layers[0].device_link.as_ref().unwrap();
assert_eq!(link.family, Family::Aquilon);
assert_eq!(link.screen, "S1");

View File

@ -134,7 +134,7 @@ fn explicit_empty_folders_survive_history_save_rename_and_membership_changes() {
fn version_12_explicit_folder_validation_and_v11_migration() {
let old = include_str!("../../../docs/interfaces/canvas-pilot-v11.example.json");
let p = Project::from_json(old).unwrap();
assert_eq!(p.version, 17);
assert_eq!(p.version, 18);
assert!(p.folders.is_empty());
let example = include_str!("../../../docs/interfaces/canvas-pilot-v12.example.json");
assert_eq!(

View File

@ -84,7 +84,7 @@ fn explicit_fit_survives_resize_undo_reordering_and_project_roundtrip() {
layout.apply(0, box_geometry()).unwrap();
assert_eq!(layout.formats().advanced[0], crop);
let before = Project::from_layout(&layout);
assert_eq!(before.version, 17);
assert_eq!(before.version, 18);
let loaded = Project::from_json(&before.to_json().unwrap()).unwrap();
assert_eq!(loaded, before);
assert_eq!(
@ -107,7 +107,7 @@ fn explicit_fit_survives_resize_undo_reordering_and_project_roundtrip() {
fn v13_migration_defaults_to_normal_crop_and_v14_requires_valid_fit() {
let text = include_str!("../../../docs/interfaces/canvas-pilot-v13.example.json");
let migrated = Project::from_json(text).unwrap();
assert_eq!(migrated.version, 17);
assert_eq!(migrated.version, 18);
assert!(migrated.layers.iter().all(|l| l.layer_fit.is_none()));
let mut json = serde_json::to_value(&migrated).unwrap();
json["layers"][0]
@ -125,7 +125,7 @@ fn current_documented_example_is_valid() {
"../../../docs/interfaces/canvas-pilot-v14.example.json"
))
.unwrap();
assert_eq!(p.version, 17);
assert_eq!(p.version, 18);
p.layout().unwrap();
}

View File

@ -103,7 +103,7 @@ fn mask_schema_migration_validation_reorder_resize_and_atomic_import() {
assert_eq!(Project::from_json(&p.to_json().unwrap()).unwrap(), p);
let old = include_str!("../../../docs/interfaces/canvas-pilot-v14.example.json");
let migrated = Project::from_json(old).unwrap();
assert_eq!(migrated.version, 17);
assert_eq!(migrated.version, 18);
assert!(migrated.layers.iter().all(|l| l.mask == Mask::default()));
let mut json = serde_json::to_value(&p).unwrap();
json["layers"][0].as_object_mut().unwrap().remove("mask");

View File

@ -234,7 +234,7 @@ fn persistent_device_links_roundtrip_migrate_and_undo() {
include_str!("../../../docs/interfaces/canvas-pilot-v5.example.json"),
] {
let p = Project::from_json(text).unwrap();
assert_eq!(p.version, 17);
assert_eq!(p.version, 18);
assert!(p.layers.iter().all(|l| l.device_link.is_none()));
}
let mut value = serde_json::to_value(&project).unwrap();
@ -311,7 +311,7 @@ fn position_point_schema_migrates_corners_and_rejects_mislabeled_files() {
.unwrap();
old["editor"]["position_corner"] = name.into();
let loaded = Project::from_json(&old.to_string()).unwrap();
assert_eq!(loaded.version, 17);
assert_eq!(loaded.version, 18);
assert_eq!(loaded.editor.position_point, expected);
old["editor"]["position_corner"] = "center".into();
assert!(Project::from_json(&old.to_string()).is_err());
@ -320,7 +320,7 @@ fn position_point_schema_migrates_corners_and_rejects_mislabeled_files() {
assert!(Project::from_json(&old.to_string()).is_err());
}
let value: serde_json::Value = serde_json::from_str(&current.to_json().unwrap()).unwrap();
for version in [0, 18] {
for version in [0, 19] {
let mut invalid = value.clone();
invalid["version"] = version.into();
assert!(
@ -361,7 +361,7 @@ fn backdrop_title_roundtrips_and_older_projects_gain_the_default() {
}
let old = include_str!("../../../docs/interfaces/canvas-pilot-v6.example.json");
let migrated = Project::from_json(old).unwrap();
assert_eq!(migrated.version, 17);
assert_eq!(migrated.version, 18);
assert_eq!(migrated.editor.backdrop_title, DEFAULT_BACKDROP_TITLE);
let mut invalid: serde_json::Value = serde_json::from_str(old).unwrap();
invalid["editor"]["backdrop_title"] = "Unexpected".into();
@ -432,7 +432,7 @@ fn saved_pivots_roundtrip_and_old_projects_default_to_center() {
assert_eq!(loaded.layer_info(0).pivot, custom);
assert_eq!(loaded.layer_info(1).pivot, [0.5; 2]);
let example = include_str!("../../../docs/interfaces/canvas-pilot-v9.example.json");
assert_eq!(Project::from_json(example).unwrap().version, 17);
assert_eq!(Project::from_json(example).unwrap().version, 18);
let old = include_str!("../../../docs/interfaces/canvas-pilot-v8.example.json");
let migrated = Project::from_json(old).unwrap();
assert!(migrated.layers.iter().all(|l| l.pivot == [0.5; 2]));
@ -464,7 +464,7 @@ fn reference_collection_migrates_single_images_and_rejects_mislabeled_or_oversiz
let reference = serde_json::json!({"name":"guide.png","image_base64":STANDARD.encode(b"image bytes"),"visible":false,"opacity":0.4,"preserve_ratio":true,"native_size":false,"offset":[0.0,0.0]});
old["reference"] = reference.clone();
let migrated = Project::from_json(&old.to_string()).unwrap();
assert_eq!(migrated.version, 17);
assert_eq!(migrated.version, 18);
assert_eq!(migrated.references.len(), 1);
assert!(!migrated.references[0].visible);
assert_eq!(migrated.references[0].opacity, 0.4);
@ -484,7 +484,7 @@ fn reference_collection_migrates_single_images_and_rejects_mislabeled_or_oversiz
gallery.references = vec![migrated.references[0].clone(); 33];
assert!(gallery.to_json().unwrap_err().contains("32 reference"));
let example = include_str!("../../../docs/interfaces/canvas-pilot-v10.example.json");
assert_eq!(Project::from_json(example).unwrap().version, 17);
assert_eq!(Project::from_json(example).unwrap().version, 18);
}
#[test]
@ -611,7 +611,7 @@ fn workspace_roundtrip_migration_and_validation() {
fn input_proposals_migrate_validate_and_require_explicit_version_16() {
let old = include_str!("../../../docs/interfaces/canvas-pilot-v15.example.json");
let migrated = Project::from_json(old).unwrap();
assert_eq!(migrated.version, 17);
assert_eq!(migrated.version, 18);
assert!(migrated.input_proposals.is_empty());
let fixture = include_str!("../../../docs/interfaces/canvas-pilot-v16.example.json");
let project = Project::from_json(fixture).unwrap();
@ -658,3 +658,26 @@ fn input_proposals_migrate_validate_and_require_explicit_version_16() {
.push(project.input_proposals[0].clone());
assert!(duplicate.to_json().is_err());
}
#[test]
fn mask_snapping_migration_and_strict_round_trip() {
let old = include_str!("../../../docs/interfaces/canvas-pilot-v17.example.json");
let current = include_str!("../../../docs/interfaces/canvas-pilot-v18.example.json");
let mut project = Project::from_json(old).unwrap();
assert_eq!(project, Project::from_json(current).unwrap());
assert!(!project.workspace.snapping.mask_edges);
project.workspace.snapping.mask_edges = true;
assert_eq!(
Project::from_json(&project.to_json().unwrap()).unwrap(),
project
);
let mut value = serde_json::to_value(project).unwrap();
value["version"] = 17.into();
assert!(Project::from_json(&value.to_string()).is_err());
value["version"] = 18.into();
value["workspace"]["snapping"]
.as_object_mut()
.unwrap()
.remove("mask_edges");
assert!(Project::from_json(&value.to_string()).is_err());
}

View File

@ -651,6 +651,7 @@ fn overlay_grid_snaps_moves_resizes_and_pivots_with_fractional_divisions() {
grid: true,
show_grid: false,
grid_divisions: [7, 5],
mask_edges: false,
};
let mut layout = Layout::default();
let x = 1920.0 / 7.0;
@ -703,3 +704,236 @@ fn overlay_grid_snaps_moves_resizes_and_pivots_with_fractional_divisions() {
65
);
}
fn mask_options() -> Snapping {
Snapping {
enabled: true,
pixels: false,
screen_edges: false,
layer_edges: false,
mask_edges: true,
..Default::default()
}
}
#[test]
fn masked_edges_snap_movement_pivot_and_resize_for_both_origins() {
use canvas_pilot::{
ResizeHandle,
formats::{Mask, MaskOrigin},
};
for origin in [MaskOrigin::Layer, MaskOrigin::Source] {
let mut layout = Layout::default();
layout
.set_mask(
0,
Mask {
origin,
right: 0.25,
..Default::default()
},
)
.unwrap();
layout.set_locked(0, true);
// First layer ends at 760, its picture at 600.
let target = 600.0;
let options = mask_options();
assert_eq!(
layout
.snap_pivot(1, [target + 3.0, 300.0], options, 6.0, None, false)
.0[0],
target
);
let original = layout.layers().clone();
layout.start_drag([1160.0, 200.0]);
assert_eq!(
layout.drag_to_snapped([target + 3.0, 210.0], options, 6.0)[0],
Some(target)
);
assert_eq!(layout.layers()[1].x, target);
layout.finish_drag();
layout.undo();
assert_eq!(*layout.layers(), original);
layout.select(Some(1));
layout.start_handle_resize(1, ResizeHandle::Left, [1160.0, 360.0], false);
assert_eq!(
layout.drag_to_snapped([target + 3.0, 360.0], options, 6.0)[0],
Some(target)
);
assert_eq!(layout.layers()[1].x, target);
assert_eq!(layout.layers()[1].x + layout.layers()[1].width, 1800.0);
layout.cancel_drag();
for hidden in [false, true] {
layout.set_visible(0, !hidden);
let mut disabled = options;
disabled.mask_edges = false;
assert_eq!(
layout
.snap_pivot(1, [603.0, 300.0], disabled, 6.0, None, false)
.1[0],
None
);
assert_eq!(
layout
.snap_pivot(1, [603.0, 300.0], options, 6.0, None, false)
.1[0],
if hidden { None } else { Some(600.0) }
);
}
}
}
#[test]
fn moving_mask_edges_align_without_changing_masks_and_groups_remain_rigid() {
use canvas_pilot::formats::Mask;
let mut layout = Layout::default();
layout
.set_mask(
1,
Mask {
left: 0.25,
..Default::default()
},
)
.unwrap();
let formats = layout.formats().clone();
layout.start_drag([1200.0, 200.0]);
// Moving left mask edge is 160 pixels inside the layer.
assert_eq!(
layout.drag_to_snapped([643.0, 210.0], mask_options(), 6.0)[0],
Some(760.0)
);
assert_eq!(layout.layers()[1].x, 600.0);
assert_eq!(*layout.formats(), formats);
layout.cancel_drag();
layout
.set_mask(
1,
Mask {
left: 0.2,
..Default::default()
},
)
.unwrap();
layout.set_selection([true, true]);
layout.start_drag([1200.0, 200.0]);
let before = layout.layers().clone();
let options = Snapping {
screen_edges: true,
..mask_options()
};
// Selected layers cannot target one another; a mask edge can target the output.
assert_eq!(
layout.drag_to_snapped([875.0, 210.0], options, 6.0)[0],
Some(960.0)
);
assert_eq!(
layout.layers()[1].x - layout.layers()[0].x,
before[1].x - before[0].x
);
layout.cancel_drag();
assert_eq!(*layout.layers(), before);
}
#[test]
fn fully_masked_targets_are_ignored_and_source_masks_are_clipped_to_layer() {
use canvas_pilot::formats::{Framing, Mask, MaskOrigin};
let mut layout = Layout::default();
layout
.set_mask(
0,
Mask {
left: 0.5,
right: 0.5,
..Default::default()
},
)
.unwrap();
assert_eq!(
layout
.snap_pivot(1, [443.0, 300.0], mask_options(), 6.0, None, false)
.1,
[None; 2]
);
layout
.set_mask(
0,
Mask {
origin: MaskOrigin::Source,
left: 0.3,
..Default::default()
},
)
.unwrap();
layout
.set_framing(
0,
Framing {
zoom: 2.0,
..Default::default()
},
)
.unwrap();
// Source is now twice the aperture: 120 + (0.30 - 0.25) * 1280 = 184.
assert_eq!(
layout
.snap_pivot(1, [187.0, 300.0], mask_options(), 6.0, None, false)
.1[0],
Some(184.0)
);
assert_eq!(
layout
.snap_pivot(1, [763.0, 300.0], mask_options(), 6.0, None, false)
.1[0],
Some(760.0)
);
assert_eq!(
layout
.snap_pivot(1, [1083.0, 300.0], mask_options(), 6.0, None, false)
.1[0],
None
);
}
#[test]
fn mask_targets_follow_all_fit_modes_and_skip_letterbox_space() {
use canvas_pilot::formats::{LayerFit, Mask, MaskOrigin};
for fit in LayerFit::ALL {
for origin in [MaskOrigin::Layer, MaskOrigin::Source] {
let mut layout = Layout::default();
let mut g = layout.layers()[0];
g.height = 600.0;
layout.apply(0, g).unwrap();
layout
.set_layer_fit(0, Some(fit), Default::default())
.unwrap();
layout
.set_mask(
0,
Mask {
origin,
left: 0.3,
top: 0.3,
..Default::default()
},
)
.unwrap();
let mask = layout.formats().mask_bounds(0, g).unwrap();
let picture = fit.image([1920.0, 1080.0], g).unwrap();
let expected = [
g.x.max(mask.x).max(picture.x),
g.y.max(mask.y).max(picture.y),
];
let (actual, guides) = layout.snap_pivot(
1,
expected.map(|v| v + 2.0),
mask_options(),
6.0,
None,
false,
);
assert_eq!(actual, expected, "{fit:?} {origin:?}");
assert_eq!(guides, expected.map(Some));
}
}
}

View File

@ -4,6 +4,16 @@
## Unreleased
### v0.9.13
- Added optional Mask edges snapping for movement, resize targets and pivots,
using layer/source mask bounds clipped to the layer aperture. Moving mask
edges can align alongside outer layer edges; hidden and fully masked targets
are ignored. Resize handles and mirrored contact retain outer-edge geometry.
- Project v18 and settings v14 persist the option; older files migrate with it
disabled. Added regression coverage for masked targets, strict migrations and
the saved UI toggle. Whole-application line coverage: 91.54%.
### v0.9.12
- Added Reset mask to the layer context menu, preserving mask origin, crop, fit and

View File

@ -154,6 +154,22 @@ Navigation tool choice survives selection changes and project loads in the curre
session; a new launch starts with Select. Pan/Zoom do not alter geometry, crop values
or document history. Existing project saves still preserve zoom/pan values.
### Snap to masks
Enable **Mask edges** in the snapping options to add the visible mask boundaries
as targets, independently of **Visible layer edges**. Movement can align either
outer layer edges or mask edges to those targets, screen guides and grid lines.
Resize handles and pivots can snap to stationary layers’ mask boundaries;
resize handles still belong to the outer layer rectangle. Mirrored/opposite
resize contact remains based on outer layer edges.
Both layer-relative and source-relative masks are supported, including source
crop, pan and zoom. Mask bounds are clipped to the layer aperture and fitted picture, so empty
letterbox margins add no mask targets; fully masked
areas and hidden layers supply no mask targets. Locked visible layers still do.
This option starts disabled and is saved in preferences and projects. Crop and
mask-editing gestures remain free of snapping.
### Persistent editing tools
The toolbar’s **Snap ▾** dropdown groups the **10 px grid** and **100 px grid**

View File

@ -7,7 +7,7 @@ not a named project export. Headless/default editors never access this path.
| Field | Meaning |
| --- | --- |
| `version` | Integer `1`; other versions rejected |
| `project` | Complete [project v17](canvas-pilot.md), including embedded reference bytes; its units, precision and validation apply without display rounding |
| `project` | Complete [project v18](canvas-pilot.md), including embedded reference bytes; its units, precision and validation apply without display rounding |
| `project_path` | Last opened/successfully saved named JSON path, or null; geometry exports do not change it |
| `manual_saved_at` | Unix UTC seconds of the last successful explicit project save, or null when unknown; recovery and measurement-point autosaves do not update it |
@ -34,7 +34,7 @@ last successful writer wins.
Recovery retains applied values only: no undo history, pending text/format/import
drafts, transient tools, or credentials. A normal exit cancels unfinished canvas
gestures before the final checkpoint. The schema does not replace named project
JSON: Save continues to emit a bare project v17 document. Opening/New replaces the
JSON: Save continues to emit a bare project v18 document. Opening/New replaces the
single recovery slot; New warns with the manual-save age and Save/Discard/Cancel.
A failed or cancelled manual save never completes Save-and-create-new.

View File

@ -0,0 +1,30 @@
{
"version": 14,
"theme": "midra",
"recent_themes": [
"midra"
],
"show_toolbar_icon_names": false,
"keep_aspect_ratio": true,
"show_source_pattern": false,
"snapping": {
"enabled": false,
"pixels": true,
"screen_edges": true,
"layer_edges": true,
"grid": false,
"show_grid": true,
"grid_divisions": [
8,
6
],
"mask_edges": false
},
"midra_host": "",
"allow_sending_to_program": false,
"autoconnect_at_startup": false,
"recent_midra_hosts": [],
"language": "system",
"ui_scale": 1.0,
"text_scale": null
}

View File

@ -1,15 +1,15 @@
# Canvas Pilot application settings, version 13
# Canvas Pilot application settings, version 14
Canvas Pilot was formerly named Midra Layout. The rename preserves existing wire-format identifiers, `.midra.json` projects, settings/recovery locations and `MIDRA_VECTORCRAFT_CLI` configuration. No schema version changes are needed. New exports use Canvas Pilot in human-readable titles; legacy files remain readable.
Implementation: `crates/canvas-pilot/src/settings.rs`. This per-user JSON file is
independent of the [project JSON and SVG contracts](canvas-pilot.md).
[Complete default example](canvas-pilot-settings-v13.example.json).
[Complete default example](canvas-pilot-settings-v14.example.json).
Version 1 files migrate automatically: the saved theme becomes the only entry in
`recent_themes`, with all other preferences preserved. The [version 1 example](canvas-pilot-settings-v1.example.json)
remains a migration fixture. Version 2 files then migrate by adding disabled
snapping with all target types enabled. The [version 2 example](canvas-pilot-settings-v2.example.json)
remains a migration fixture too. Version 3 files migrate by adding an empty `midra_host`; the [version 3 example](canvas-pilot-settings-v3.example.json) remains a migration fixture. Version 4 files migrate by adding `allow_sending_to_program: false`; the [version 4 example](canvas-pilot-settings-v4.example.json) remains a migration fixture. Version 5 files migrate with `autoconnect_at_startup: false`; the [version 5 example](canvas-pilot-settings-v5.example.json) remains a migration fixture. Version 6 files migrate with the overlay grid visible, snapping to it disabled, and `grid_divisions: [8, 6]`; the [version 6 example](canvas-pilot-settings-v6.example.json) remains a migration fixture. Version 7 migrates with an empty `recent_midra_hosts` list; the [version 7 example](canvas-pilot-settings-v7.example.json) remains a migration fixture. Version 8 migrates with `language: "system"`; the [version 8 example](canvas-pilot-settings-v8.example.json) remains a migration fixture. Version 9 migrates without changing any preferences; its `system`, `en` and `fr` values remain valid. The [version 9 example](canvas-pilot-settings-v9.example.json) remains a migration fixture. Version 10 adds language choices. Version 11 adds `ui_scale` and `text_scale`; v1–v10 settings migrate to 100% interface scale with separate text scaling disabled, preserving all existing preferences. The [version 10 example](canvas-pilot-settings-v10.example.json) remains a migration fixture. Version 12 adds `pt-PT`, `ne`, `th`, `hi` and `tok`; v1–v11 settings migrate without changing existing preferences. Values outside each old version’s language set are rejected before migration. The [version 11 example](canvas-pilot-settings-v11.example.json) remains a migration fixture. Version 13 adds installed language choices; v12 preferences migrate unchanged. The [version 12 example](canvas-pilot-settings-v12.example.json) remains a fixture. Saving writes version 13, which older applications reject.
remains a migration fixture too. Version 3 files migrate by adding an empty `midra_host`; the [version 3 example](canvas-pilot-settings-v3.example.json) remains a migration fixture. Version 4 files migrate by adding `allow_sending_to_program: false`; the [version 4 example](canvas-pilot-settings-v4.example.json) remains a migration fixture. Version 5 files migrate with `autoconnect_at_startup: false`; the [version 5 example](canvas-pilot-settings-v5.example.json) remains a migration fixture. Version 6 files migrate with the overlay grid visible, snapping to it disabled, and `grid_divisions: [8, 6]`; the [version 6 example](canvas-pilot-settings-v6.example.json) remains a migration fixture. Version 7 migrates with an empty `recent_midra_hosts` list; the [version 7 example](canvas-pilot-settings-v7.example.json) remains a migration fixture. Version 8 migrates with `language: "system"`; the [version 8 example](canvas-pilot-settings-v8.example.json) remains a migration fixture. Version 9 migrates without changing any preferences; its `system`, `en` and `fr` values remain valid. The [version 9 example](canvas-pilot-settings-v9.example.json) remains a migration fixture. Version 10 adds language choices. Version 11 adds `ui_scale` and `text_scale`; v1–v10 settings migrate to 100% interface scale with separate text scaling disabled, preserving all existing preferences. The [version 10 example](canvas-pilot-settings-v10.example.json) remains a migration fixture. Version 12 adds `pt-PT`, `ne`, `th`, `hi` and `tok`; v1–v11 settings migrate without changing existing preferences. Values outside each old version’s language set are rejected before migration. The [version 11 example](canvas-pilot-settings-v11.example.json) remains a migration fixture. Version 13 adds installed language choices; v12 preferences migrate unchanged. The [version 12 example](canvas-pilot-settings-v12.example.json) remains a fixture. Version 14 adds required `snapping.mask_edges` (false). Versions 1–13 migrate with mask snapping disabled; supplying the field under an older version is rejected. The [version 13 example](canvas-pilot-settings-v13.example.json) remains a migration fixture. Saving writes version 14, which older applications reject.
The `directories` 6 crate resolves `ProjectDirs::from("org", "beffroi", "midra-layout")`.
The filename is `settings.json` beneath `config_dir()`:
@ -26,7 +26,7 @@ unknown theme names are rejected. There are no numeric coordinates or units.
| Field | Values / default |
| --- | --- |
| `version` | Integer `13` |
| `version` | Integer `14` |
| `ui_scale` | Finite number, 0.5–4.0 inclusive; default 1.0. egui interface zoom relative to the OS display scale. |
| `text_scale` | `null` (default, disabled) or finite number 0.5–2.0 inclusive. Additional standard-widget text multiplier. |
| `language` | `"system"` (default), `"en"`, `"fr"`, `"ja"`, `"zh-CN"`, `"es"`, `"grc"`, `"eo"`, `"pt-PT"`, `"ne"`, `"th"`, `"hi"`, `"tok"`, or `{"pack":"uk"}` for an installed language. Pack identifiers use 1–63 lowercase ASCII letters, digits and hyphens, without a leading/trailing hyphen. Unknown built-in string values are rejected. |
@ -38,7 +38,7 @@ unknown theme names are rejected. There are no numeric coordinates or units.
| `show_toolbar_icon_names` | Boolean; default false |
| `keep_aspect_ratio` | Boolean; default true |
| `show_source_pattern` | Boolean; default false. Shows source patterns on other layers only during crop editing; normal editing always hides patterns. |
| `snapping` | Object with required boolean fields `enabled` (false), `pixels` (true), `screen_edges` (true; screen edges plus 25%, 50% and 75% guides on both axes), `layer_edges` (true), `grid` (false), `show_grid` (true), and `grid_divisions` ([8, 6]); unknown fields rejected |
| `snapping` | Object with required boolean fields `enabled` (false), `pixels` (true), `screen_edges` (true; screen edges plus 25%, 50% and 75% guides on both axes), `layer_edges` (true), `mask_edges` (false), `grid` (false), `show_grid` (true), and `grid_divisions` ([8, 6]); unknown fields rejected |
Scale preferences apply on startup. Slider drafts apply and save on pointer
release; typed values wait until text entry ends. UI controls
@ -143,6 +143,12 @@ fixed six-logical-pixel proximity radius converted by viewport scale. It affects
layer movement, resize handles and pivot placement; numeric entry, nudges and crop-content gestures
bypass it. Resize snapping preserves anchors and proportions and shows guides only
when the resulting edge actually reaches its target.
`mask_edges` adds the nonempty intersection of mask reveal, layer aperture and
fitted picture as edge targets. Hidden layers are skipped, locked layers included.
Movement also adds selected mask edges as anchors; resize handles remain on the
outer rectangle, with masked edges available on stationary targets. Mirrored
contact uses outer edges. The option defaults to false.
The session-only toolbar grid tools select 10 or 100 screen pixels (mutually exclusive). Shift temporarily selects the 10 px grid; Ctrl+Shift selects 100 px. If that same grid tool is selected, the matching shortcut temporarily disables it instead. Alt overrides both grids and temporarily inverts the saved snapping-enabled value (off becomes on; on becomes off), including on release. The chosen pixel/screen/layer-edge targets still apply. These modifiers do not change the saved options or settings version.
**Settings → Midra integration → Allow sending to Program** saves immediately. Restore default settings disables it. Projects do not override this application preference; the Preview/Program destination itself remains session-only.

View File

@ -0,0 +1,169 @@
{
"format": "beffroi.midra-layout",
"version": 18,
"output_resolution": {
"width": 1920,
"height": 1080
},
"inputs": [
{
"id": 1,
"source_format": "sixteen_nine",
"native_resolution": {
"width": 1920,
"height": 1080
},
"input_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
}
},
{
"id": 2,
"source_format": "sixteen_nine",
"native_resolution": {
"width": 1920,
"height": 1080
},
"input_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
}
}
],
"layers": [
{
"id": 2,
"source_id": 1,
"bounds": {
"x": 120.0,
"y": 180.0,
"width": 640.0,
"height": 360.0
},
"advanced_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
},
"visible": true,
"locked": false,
"name": "Slides",
"folder": "",
"pivot": [
0.5,
0.5
],
"device_link": {
"family": "midra4k",
"screen": "1",
"layer": "1"
},
"layer_fit": null,
"mask": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0,
"origin": "source"
}
},
{
"id": 1,
"source_id": 2,
"bounds": {
"x": 1160.0,
"y": 180.0,
"width": 640.0,
"height": 360.0
},
"advanced_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
},
"visible": true,
"locked": false,
"name": "Presenter",
"folder": "",
"pivot": [
0.5,
0.5
],
"device_link": null,
"layer_fit": "fullscreen",
"mask": {
"left": 0.1,
"right": 0.0,
"top": 0.0,
"bottom": 0.0,
"origin": "layer"
}
}
],
"editor": {
"backdrop_title": "Example Conference Name",
"selected_layer_ids": [
1
],
"position_point": "top_left",
"keep_aspect_ratio": true,
"viewport_zoom": 1.0,
"viewport_pan": [
0.0,
0.0
],
"show_source_pattern": false,
"show_toolbar_icon_names": false,
"outline_layers": false,
"position_layer_point": null
},
"next_layer_id": 3,
"references": [],
"workspace": {
"snapping": {
"enabled": false,
"pixels": true,
"screen_edges": true,
"layer_edges": true,
"grid": false,
"show_grid": true,
"grid_divisions": [
8,
6
],
"mask_edges": false
},
"resize_mode": "individual",
"grid_spacing": null,
"collapsed_folders": [],
"capture_interval_seconds": 10,
"show_empty_inputs": false,
"previews": []
},
"folders": [
"Memory A"
],
"input_proposals": [
{
"layer_id": 2,
"device_link": {
"family": "midra4k",
"screen": "1",
"layer": "1"
},
"input": "INPUT_4",
"plug": "2",
"settings": {
"aspect/pp/transformTo": "CUSTOM",
"aspect/pp/customRatio": 1778
}
}
]
}

View File

@ -7,7 +7,7 @@ These are offline editor formats, not Analog Way REST payloads. Implementation:
[`project.rs`](../../crates/canvas-pilot/tests/project.rs). Update this contract,
examples and tests in the same change as any save/export schema change.
## Project JSON, version 17
## Project JSON, version 18
Suggested filename: `layout.pilot.json`. **Open project** accepts any `.json`
filename, including legacy `.midra.json` projects, and validates the project
@ -27,7 +27,7 @@ and `next_layer_id: 3`; other values are preserved.
The [version 1 example](canvas-pilot-v1.example.json) remains a migration fixture.
Version 4 adds `editor.outline_layers: false`, and reference `native_size: false`
and `offset: [0, 0]` when migrating versions 1–3. Old fitting behavior is preserved.
Version 5 adds required `midra_link` to every layer. Versions 1–4 migrate with null links; links cannot be supplied under an older version. Version 6 renames `editor.position_corner` to `editor.position_point` and adds `center`. Versions 1–5 retain their original corner; center and the new field are rejected in those older schemas. Version 7 adds `editor.backdrop_title`; versions 1–6 gain `"Example Conference Name"` and cannot supply this field under the old schema. Version 8 adds required `editor.position_layer_point`: null keeps matched points; a point enables independent measurement. Versions 1–7 migrate to null and cannot supply this field. Version 9 adds required `layers[].pivot`; versions 1–8 migrate to `[0.5, 0.5]` and cannot supply this field. Version 10 replaces `reference` with the required ordered `references` array. Versions 1–9 migrate null to `[]` and a single image to a one-element array, preserving all image settings. Version 11 adds required `workspace` settings and embedded layer previews. Versions 1–10 gain the documented workspace defaults, with no captures or collapsed folders; supplying `workspace` in an older schema is rejected. Version 12 adds required `folders`, the explicit folder names that survive without members. Versions 1–11 gain `folders: []`, preserving their existing implicit layer grouping; supplying this field under an older version is rejected. Version 13 replaces `midra_link` with required `device_link`, adding the explicit device family. Versions 1–12 migrate numeric links to `family: "midra4k"`; null remains null, and legacy decimal IDs with leading zeros are canonicalized. Unknown legacy fields are rejected. Version 14 adds required `layers[].layer_fit`: versions 1–13 migrate to null, preserving normal crop/zoom behavior; supplying this field under an older schema is rejected. Version 15 adds required `layers[].mask`; versions 1–14 migrate with four zero edges and reject masks supplied under an older version. Version 16 adds required root `input_proposals`; versions 1–15 migrate to an empty array and reject this field if supplied under an older version. Version 17 adds required `mask.origin` (`layer` or `source`). Versions 1–16 migrate to `layer`; older versions containing `origin` are rejected. See the [version 17 example](canvas-pilot-v17.example.json); v16 remains a migration fixture. Saving always writes version 17; older applications reject it.
Version 5 adds required `midra_link` to every layer. Versions 1–4 migrate with null links; links cannot be supplied under an older version. Version 6 renames `editor.position_corner` to `editor.position_point` and adds `center`. Versions 1–5 retain their original corner; center and the new field are rejected in those older schemas. Version 7 adds `editor.backdrop_title`; versions 1–6 gain `"Example Conference Name"` and cannot supply this field under the old schema. Version 8 adds required `editor.position_layer_point`: null keeps matched points; a point enables independent measurement. Versions 1–7 migrate to null and cannot supply this field. Version 9 adds required `layers[].pivot`; versions 1–8 migrate to `[0.5, 0.5]` and cannot supply this field. Version 10 replaces `reference` with the required ordered `references` array. Versions 1–9 migrate null to `[]` and a single image to a one-element array, preserving all image settings. Version 11 adds required `workspace` settings and embedded layer previews. Versions 1–10 gain the documented workspace defaults, with no captures or collapsed folders; supplying `workspace` in an older schema is rejected. Version 12 adds required `folders`, the explicit folder names that survive without members. Versions 1–11 gain `folders: []`, preserving their existing implicit layer grouping; supplying this field under an older version is rejected. Version 13 replaces `midra_link` with required `device_link`, adding the explicit device family. Versions 1–12 migrate numeric links to `family: "midra4k"`; null remains null, and legacy decimal IDs with leading zeros are canonicalized. Unknown legacy fields are rejected. Version 14 adds required `layers[].layer_fit`: versions 1–13 migrate to null, preserving normal crop/zoom behavior; supplying this field under an older schema is rejected. Version 15 adds required `layers[].mask`; versions 1–14 migrate with four zero edges and reject masks supplied under an older version. Version 16 adds required root `input_proposals`; versions 1–15 migrate to an empty array and reject this field if supplied under an older version. Version 17 adds required `mask.origin` (`layer` or `source`). Versions 1–16 migrate to `layer`; older versions containing `origin` are rejected. See the [version 17 example](canvas-pilot-v17.example.json); v16 remains a migration fixture. Version 18 adds required `workspace.snapping.mask_edges` (default false). Versions 1–17 migrate with this option disabled; supplying it under an older schema is rejected. See the [version 18 example](canvas-pilot-v18.example.json). Saving always writes version 18; older applications reject it.
Incompatible files are never partially applied.
[Complete example](canvas-pilot-v17.example.json) is a valid project with an empty `Memory A` folder, a Midra link and an inactive input correction proposal,
@ -38,7 +38,7 @@ It is loaded by the regression tests.
| Root field | Representation / meaning |
| --- | --- |
| `format` | Exactly `"beffroi.midra-layout"` |
| `version` | Integer `17` |
| `version` | Integer `18` |
| `input_proposals` | Required array, 0–256 inactive correction proposals; at most one per existing layer, with an exactly matching `device_link`. See below. |
| `folders` | Required array of 0–256 unique explicit folder names, each trimmed and 1–128 characters. Explicit folders remain even with no members; layer folder labels also form implicit groups. |
| `next_layer_id` | Positive integer strictly greater than every layer ID; not rewound by undo |
@ -260,7 +260,7 @@ and `viewBox="0 0 W H"` equal to the output screen. The root carries
## Compatibility changes
Project version 17 and the versioned geometry exchanges are strict contracts. A breaking project field/meaning change must bump
Project version 18 and the versioned geometry exchanges are strict contracts. A breaking project field/meaning change must bump
`version` and either implement a tested migration or clearly reject older/newer
files. Changing rectangle/marker semantics requires a corresponding documented
exchange-interface revision and importer tests. Update this document and its example
@ -278,7 +278,7 @@ retarget existing links; choosing a destination there explicitly replaces that
layer's saved link. Direct send/load actions use each layer's saved screen,
independently of the screen currently displayed in the configuration window.
Automatic session recovery wraps this project representation in a separate [recovery file](canvas-pilot-recovery.md); named project JSON is version 17.
Automatic session recovery wraps this project representation in a separate [recovery file](canvas-pilot-recovery.md); named project JSON is version 18.
## Folder-scoped Midra transfers
@ -309,7 +309,7 @@ migration rules are unchanged. These IDs do not select or route physical inputs.
| Field | Representation / validation / migration default |
| --- | --- |
| `snapping` | Required booleans `enabled` (false), `pixels` (true), `screen_edges` (true), `layer_edges` (true), `grid` (false), `show_grid` (true), and `grid_divisions` (two integers 1–64, default `[8,6]`). These override application defaults for the opened project. |
| `snapping` | Required booleans `enabled` (false), `pixels` (true), `screen_edges` (true), `layer_edges` (true), `mask_edges` (false), `grid` (false), `show_grid` (true), and `grid_divisions` (two integers 1–64, default `[8,6]`). These override application defaults for the opened project. |
| `resize_mode` | `individual` (default), `same`, `mirror`, or `opposite` |
| `grid_spacing` | null (default), 10 or 100, in output pixels |
| `collapsed_folders` | Unique existing nonempty folder names (including empty explicit folders); default `[]`. Deleted/renamed stale entries are omitted when saving. |
@ -344,7 +344,7 @@ background export behavior.
For the complete persistence audit and the reasons for keeping other controls
out of project files, see [Project persistence audit](canvas-pilot-persistence-audit.md).
Device links distinguish family, screen/auxiliary and layer. A link from another family cannot be used on the current device without explicit remapping. Multiple editor layers may share one destination; a send scope containing duplicates is rejected with the conflicting layer names. Device state and physical bank roles are never saved in the project. Geometry-only exports omit these links; embedded editor snapshots retain version 17 and use the same migration on import.
Device links distinguish family, screen/auxiliary and layer. A link from another family cannot be used on the current device without explicit remapping. Multiple editor layers may share one destination; a send scope containing duplicates is rejected with the conflicting layer names. Device state and physical bank roles are never saved in the project. Geometry-only exports omit these links; embedded editor snapshots retain version 18 and use the same migration on import.
### Explicit layer fit (v14)

View File

@ -27,7 +27,7 @@ external editor moves/resizes a shape without updating the embedded snapshot.
| FigCraft FIGCRAFT | First page node `plugin_data.beffroi_midra_parameters` in native v1 `document.json` | ZIP and bare JSON restore supported. Native FigCraft 0.5.1 load/save preserves the field. Duplicate payloads are rejected; document JSON reads are bounded to 16 MiB. Other ZIP members are preserved. |
| Figma FIG | Not enabled | Figma has plugin data, but the installed FigCraft 0.5.1 native exporter explicitly warns `plugin data was left out`. Its model field is not evidence of native preservation. |
| Illustrator | Not enabled | PDF-compatible Illustrator can have document metadata, but the current VectorCraft SVG↔Illustrator conversion path has no verified application-payload preservation. No unverified PDF/Illustrator trailer changes are made. |
| Midra project JSON | Already complete | Project v17 remains the authoritative full-fidelity save. |
| Midra project JSON | Already complete | Project v18 remains the authoritative full-fidelity save. |
Unsupported codecs disable the option with an explanation. Programmatic attempts
to request the extension on those codecs fail explicitly, never silently discard
@ -36,7 +36,7 @@ it. Vendor availability and the `no_proprietary` build flag still apply.
## Payload contract (extension version 1)
`BASE64` is standard padded RFC 4648 base64 of UTF-8, pretty-printed
[project JSON](canvas-pilot.md), currently version 17. It is inert data, not an
[project JSON](canvas-pilot.md), currently version 18. It is inert data, not an
executable instruction, URL or file path. Project format/version and validation
remain authoritative. Future incompatible carrier/payload meanings require a new
extension version and explicit migration or rejection.