Skip to content

LightCraft: An open-source non-destructive photo editor written by scratch in pure Rust

Issue #92: XMP: merge into an existing sidecar instead of replacing it

Brandon Thomas882a059fac37
diff --git a/crates/engine/src/cmd/query.rs b/crates/engine/src/cmd/query.rs
index 09fbbbdbf..e7ffde143 100644
--- a/crates/engine/src/cmd/query.rs
+++ b/crates/engine/src/cmd/query.rs
@@ -113,7 +113,7 @@ pub fn specs() -> Vec<CommandSpec> {
.map(|r| json!({"group": r.group, "tag": r.tag, "name": r.name, "value": r.value}))
.collect();
// XMP: the sidecar if there is one, else the file's own packet
- let packet = crate::sidecar::read_packet(path, ph.kind, s.xmp.naming).map(|(x, _)| x).or_else(|| lightcraft_meta::embedded(&bytes).xmp);
+ let packet = crate::sidecar::read_packet(path, ph.kind, s.sidecar_naming(ph.id)).map(|(x, _)| x).or_else(|| lightcraft_meta::embedded(&bytes).xmp);
let xmp: Vec<Value> = packet
.and_then(|x| lightcraft_meta::parse_xmp(&x).ok())
.map(|d| d.properties.into_iter().filter(|(k, _)| !k.starts_with("lc:")).map(|(k, v)| json!({"name": k, "value": v.join("; ")})).collect())
diff --git a/crates/engine/src/cmd/xmp.rs b/crates/engine/src/cmd/xmp.rs
index 7b7d4325e..b83e72755 100644
--- a/crates/engine/src/cmd/xmp.rs
+++ b/crates/engine/src/cmd/xmp.rs
@@ -9,14 +9,26 @@ use crate::{Result, Session};
fn save(s: &mut Session, p: &Value) -> Result<Value> {
let mut written = Vec::new();
+ let mut merged = Vec::new();
+ let mut backups = Vec::new();
let mut failed = Vec::new();
+ let owners = crate::sidecar::StemOwners::of(&s.catalog);
for id in s.targets(p) {
- match s.save_sidecar(id) {
- Ok(path) => written.push(path.display().to_string()),
+ match s.save_sidecar_with(id, &owners) {
+ Ok(r) => {
+ let path = r.path.display().to_string();
+ if r.merged {
+ merged.push(path.clone());
+ }
+ if let Some(b) = r.backup {
+ backups.push(json!({"path": path, "backup": b.display().to_string()}));
+ }
+ written.push(path);
+ }
Err(e) => failed.push(json!({"id": id.0, "error": e.to_string()})),
}
}
- Ok(json!({"written": written, "failed": failed}))
+ Ok(json!({"written": written, "merged": merged, "backups": backups, "failed": failed}))
}
fn read(s: &mut Session, p: &Value) -> Result<Value> {
@@ -63,7 +75,7 @@ pub fn specs() -> Vec<CommandSpec> {
"Save Metadata to File",
["Photo"],
Some("Cmd+S"),
- "{ids?} — writes each photo's XMP sidecar (metadata + develop settings) next to the original → {written: [path], failed}",
+ "{ids?} — writes each photo's XMP sidecar (metadata + develop settings) next to the original, merged into an existing one (other apps' data kept; an unreadable one is backed up first) → {written: [path], merged: [path], backups: [{path, backup}], failed}",
has_selection,
save
),
diff --git a/crates/engine/src/sidecar.rs b/crates/engine/src/sidecar.rs
index a49e5feef..7b65a98a6 100644
--- a/crates/engine/src/sidecar.rs
+++ b/crates/engine/src/sidecar.rs
@@ -5,12 +5,25 @@
//! creator, keywords, capture time and GPS in the standard namespaces, plus our complete develop
//! settings (`lc:settings`, JSON), the pick/reject flag (`lc:flag`) and location (`lc:location`).
//!
+//! An existing sidecar is never replaced wholesale (issue #92): LightCraft's properties
+//! ([`OWNED`], [`OWNED_IF_STATED`]) are merged into it ([`lightcraft_meta::merge_xmp`]) and
+//! everything else — another editor's `crs:` develop settings, `xmpMM` history, unknown
+//! namespaces — is kept byte for byte. A sidecar that can't be read as XMP is first copied to
+//! `<name>.xmp.bak-<time>` (never overwritten), then replaced. Writes are atomic (temp file,
+//! fsync, rename).
+//!
+//! **Shared names** (Stem naming): `IMG_0001.CR3` and `IMG_0001.JPG` would share `IMG_0001.xmp`.
+//! When two catalogued files map to one stem sidecar, it belongs to one of them (a raw first, then
+//! the first by file name — [`Session::sidecar_naming`]); the others use `<file>.xmp`
+//! (`IMG_0001.JPG.xmp`) for writing and reading, so neither overwrites the other.
+//!
//! **Read** (on import, and `photo.readMetadataFromFile`): the sidecar wins for metadata, except
//! the capture time: a time embedded in the file wins, and the sidecar's (`exif:DateTimeOriginal`,
//! else `photoshop:DateCreated`, else `xmp:CreateDate`) fills in only when the file has none; develop
//! settings are restored from `lc:settings` when present, else mapped from interoperable `crs:`
//! fields ([`crate::crs`]). For raw/DNG files without a sidecar the file's embedded XMP is used.
+use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::Arc;
@@ -258,13 +271,110 @@ pub fn sidecar_packet(p: &Photo, cat: &lightcraft_catalog::Catalog) -> String {
lightcraft_meta::write_xmp_lc(&meta, &lc)
}
-/// Write `data` to `path` atomically (temp file + rename).
+/// The properties LightCraft writes and owns in a sidecar: replaced on every save (removed when
+/// LightCraft has no value, so clearing a field clears it in the file too). All of them are read
+/// back on import and by Read Metadata from File.
+pub const OWNED: &[&str] = &[
+ "xmp:Rating",
+ "xmp:Label",
+ "dc:title",
+ "dc:description",
+ "dc:rights",
+ "dc:creator",
+ "dc:subject",
+ "Iptc4xmpCore:Location",
+ "Iptc4xmpCore:AltTextAccessibility",
+ "Iptc4xmpCore:ExtDescrAccessibility",
+ "photoshop:City",
+ "photoshop:State",
+ "photoshop:Country",
+ "xmpRights:Marked",
+ "xmpRights:UsageTerms",
+ "xmpRights:WebStatement",
+ "lc:*",
+];
+
+/// Properties replaced only when LightCraft has a value (capture time; GPS, which LightCraft
+/// doesn't read from sidecars): otherwise the sidecar's own value stays. Anything else LightCraft
+/// writes (`xmp:CreatorTool`) goes only into new sidecars.
+pub const OWNED_IF_STATED: &[&str] = &["exif:DateTimeOriginal", "photoshop:DateCreated", "exif:GPSLatitude", "exif:GPSLongitude"];
+
+/// Write `data` to `path` atomically: a temp file next to it, synced, then renamed over it.
fn write_atomic(path: &Path, data: &[u8]) -> std::io::Result<()> {
+ use std::io::Write;
let tmp = path.with_extension(format!("xmp.tmp-{}", std::process::id()));
- std::fs::write(&tmp, data)?;
- std::fs::rename(&tmp, path).inspect_err(|_| {
+ let r = (|| {
+ let mut f = std::fs::File::create(&tmp)?;
+ f.write_all(data)?;
+ f.sync_all()?;
+ std::fs::rename(&tmp, path)
+ })();
+ if r.is_err() {
let _ = std::fs::remove_file(&tmp);
- })
+ }
+ r
+}
+
+/// Copy `path` to a new `<name>.bak-<stamp>` (`-1`, `-2`… if taken; never overwriting).
+fn backup(path: &Path, stamp: &str) -> std::io::Result<PathBuf> {
+ use std::io::Write;
+ let bytes = std::fs::read(path)?;
+ let stamp: String = stamp.chars().filter(char::is_ascii_alphanumeric).collect();
+ let name = path.file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_default();
+ for k in 0..1000 {
+ let b = path.with_file_name(if k == 0 { format!("{name}.bak-{stamp}") } else { format!("{name}.bak-{stamp}-{k}") });
+ match std::fs::OpenOptions::new().write(true).create_new(true).open(&b) {
+ Ok(mut f) => {
+ f.write_all(&bytes)?;
+ f.sync_all()?;
+ return Ok(b);
+ }
+ Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
+ Err(e) => return Err(e),
+ }
+ }
+ Err(std::io::Error::other("no free backup name"))
+}
+
+/// What [`Session::save_sidecar`] did.
+#[derive(Clone, Debug, PartialEq)]
+pub struct SidecarSaved {
+ pub path: PathBuf,
+ /// An existing sidecar was merged into (its other contents kept).
+ pub merged: bool,
+ /// An existing sidecar that couldn't be read as XMP was copied here before being replaced.
+ pub backup: Option<PathBuf>,
+}
+
+/// The new contents for the sidecar at `path`: `fresh` merged into the existing file, if any.
+/// Returns (contents, merged, backup).
+fn sidecar_contents(path: &Path, fresh: String, stamp: &str) -> std::io::Result<(String, bool, Option<PathBuf>)> {
+ let bytes = match std::fs::read(path) {
+ Ok(b) => b,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok((fresh, false, None)),
+ // can't see what is there: never overwrite it blindly
+ Err(e) => return Err(e),
+ };
+ if bytes.iter().all(u8::is_ascii_whitespace) {
+ return Ok((fresh, false, None));
+ }
+ let rules = lightcraft_meta::MergeRules { owned: OWNED, owned_if_present: OWNED_IF_STATED };
+ match std::str::from_utf8(&bytes)
+ .map_err(|e| e.to_string())
+ .and_then(|old| lightcraft_meta::merge_xmp(old, &fresh, rules).map_err(|e| e.to_string()))
+ {
+ Ok(merged) => Ok((merged, true, None)),
+ Err(why) => {
+ let b = backup(path, stamp)?;
+ log::warn!("{}: not readable as XMP ({why}); kept a copy as {} before replacing it", path.display(), b.display());
+ Ok((fresh, false, Some(b)))
+ }
+ }
+}
+
+/// Key of the stem sidecar a file maps to (case-insensitive).
+fn stem_key(original: &str) -> String {
+ sidecar_path(original, SidecarNaming::Stem).to_string_lossy().to_lowercase()
}
fn file_path(p: &Photo) -> Option<&str> {
@@ -302,24 +412,70 @@ pub(crate) fn op_photos(op: &Op, out: &mut Vec<PhotoId>) {
}
}
+/// Which photo owns each stem sidecar that several catalogued files map to (see
+/// [`Session::sidecar_naming`]).
+pub(crate) struct StemOwners(HashMap<String, PhotoId>);
+
+impl StemOwners {
+ pub(crate) fn of(cat: &lightcraft_catalog::Catalog) -> StemOwners {
+ // per stem: (raw first, then file name, then id) of the best candidate; and how many
+ let mut best: HashMap<String, ((bool, String, u64), PhotoId, usize)> = HashMap::new();
+ for p in cat.photos().filter(|p| p.copy_of.is_none()) {
+ let Some(path) = file_path(p) else { continue };
+ let rank = (p.kind != MediaKind::Raw, path.to_lowercase(), p.id.0);
+ let e = best.entry(stem_key(path)).or_insert_with(|| (rank.clone(), p.id, 0));
+ e.2 += 1;
+ if rank < e.0 {
+ (e.0, e.1) = (rank, p.id);
+ }
+ }
+ StemOwners(best.into_iter().filter(|(_, v)| v.2 > 1).map(|(k, v)| (k, v.1)).collect())
+ }
+
+ /// `naming` for photo `p`, except that a stem sidecar another file owns becomes Full.
+ fn naming(&self, p: &Photo, naming: SidecarNaming) -> SidecarNaming {
+ match (naming, file_path(p)) {
+ (SidecarNaming::Stem, Some(path)) if self.0.get(&stem_key(path)).is_some_and(|owner| *owner != p.id) => SidecarNaming::Full,
+ _ => naming,
+ }
+ }
+}
+
impl Session {
- /// Write the photo's XMP sidecar; returns its path.
- pub fn save_sidecar(&self, id: PhotoId) -> Result<PathBuf> {
+ /// The sidecar naming for photo `id`: the library's, except under Stem naming when another
+ /// catalogued file shares the stem (`IMG_0001.CR3` + `IMG_0001.JPG`) and owns the stem
+ /// sidecar — a raw first, else the first by file name. The others use Full naming
+ /// (`IMG_0001.JPG.xmp`), so their metadata never overwrites each other.
+ pub fn sidecar_naming(&self, id: PhotoId) -> SidecarNaming {
+ match self.catalog.photo(id) {
+ Some(p) if self.xmp.naming == SidecarNaming::Stem => StemOwners::of(&self.catalog).naming(p, self.xmp.naming),
+ _ => self.xmp.naming,
+ }
+ }
+
+ /// Write the photo's XMP sidecar, merged into an existing one (see the module docs).
+ pub fn save_sidecar(&self, id: PhotoId) -> Result<SidecarSaved> {
+ self.save_sidecar_with(id, &StemOwners::of(&self.catalog))
+ }
+
+ pub(crate) fn save_sidecar_with(&self, id: PhotoId, owners: &StemOwners) -> Result<SidecarSaved> {
let p = self.catalog.photo(id).ok_or(lightcraft_catalog::CatalogError::NoPhoto(id))?;
if p.copy_of.is_some() {
return Err(EngineError::Other(format!("{} is a virtual copy: its settings live only in the library", p.file_name)));
}
let orig = file_path(p).ok_or_else(|| EngineError::Other(format!("{} is not a file on disk", p.file_name)))?;
- let path = sidecar_path(orig, self.xmp.naming);
- write_atomic(&path, sidecar_packet(p, &self.catalog).as_bytes()).map_err(|e| EngineError::Other(format!("{}: {e}", path.display())))?;
- Ok(path)
+ let path = sidecar_path(orig, owners.naming(p, self.xmp.naming));
+ let err = |e: std::io::Error| EngineError::Other(format!("{}: {e}", path.display()));
+ let (data, merged, backup) = sidecar_contents(&path, sidecar_packet(p, &self.catalog), &(self.clock)()).map_err(err)?;
+ write_atomic(&path, data.as_bytes()).map_err(err)?;
+ Ok(SidecarSaved { path, merged, backup })
}
/// The op that applies a photo's sidecar (or embedded XMP) to the catalog, if there is one.
pub fn read_sidecar_op(&self, id: PhotoId) -> Result<Option<(Op, PathBuf)>> {
let p = self.catalog.photo(id).ok_or(lightcraft_catalog::CatalogError::NoPhoto(id))?;
let Some(orig) = file_path(p) else { return Ok(None) };
- let Some((packet, from)) = read_packet(orig, p.kind, self.xmp.naming) else { return Ok(None) };
+ let Some((packet, from)) = read_packet(orig, p.kind, self.sidecar_naming(id)) else { return Ok(None) };
let sc = parse_sidecar(&packet, p.kind == MediaKind::Raw)
.map_err(|e| EngineError::Other(format!("{}: {e}", from.display())))?
.resolve_label(&self.catalog);
@@ -344,9 +500,13 @@ impl Session {
pub(crate) fn auto_write_sidecars(&self, ops: &[Op]) {
let mut ids = Vec::new();
ops.iter().for_each(|o| op_photos(o, &mut ids));
+ if ids.is_empty() {
+ return;
+ }
+ let owners = StemOwners::of(&self.catalog);
for id in ids {
if self.catalog.photo(id).is_some_and(|p| file_path(p).is_some() && p.copy_of.is_none())
- && let Err(e) = self.save_sidecar(id)
+ && let Err(e) = self.save_sidecar_with(id, &owners)
{
log::warn!("auto-write XMP: {e}");
}
diff --git a/crates/engine/src/tests_xmp.rs b/crates/engine/src/tests_xmp.rs
index 00b8e3b08..b6474e394 100644
--- a/crates/engine/src/tests_xmp.rs
+++ b/crates/engine/src/tests_xmp.rs
@@ -576,3 +576,132 @@ fn copyright_status_usage_terms_and_url_round_trip() {
let _ = std::fs::remove_dir_all(&src);
let _ = std::fs::remove_dir_all(&lib);
}
+
+/// A sidecar another raw developer wrote: develop settings in attributes and elements, a
+/// structured edit history, an unknown namespace.
+const OTHER_APP_SIDECAR: &str = r#"<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
+<x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="Other Toolkit">
+ <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+ <rdf:Description rdf:about=""
+ xmlns:xmp="http://ns.adobe.com/xap/1.0/"
+ xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"
+ xmlns:stEvt="http://ns.adobe.com/xap/1.0/sType/ResourceEvent#"
+ xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
+ xmlns:other="http://example.com/other/1.0/"
+ xmp:Rating="2"
+ crs:Version="99.0"
+ crs:Exposure2012="+0.65"
+ crs:HasSettings="True"
+ other:Secret="keep me">
+ <xmpMM:History>
+ <rdf:Seq>
+ <rdf:li stEvt:action="derived" stEvt:parameters="converted from image/x-raw to image/png"/>
+ </rdf:Seq>
+ </xmpMM:History>
+ <crs:ToneCurvePV2012>
+ <rdf:Seq>
+ <rdf:li>0, 0</rdf:li>
+ <rdf:li>128, 140</rdf:li>
+ <rdf:li>255, 255</rdf:li>
+ </rdf:Seq>
+ </crs:ToneCurvePV2012>
+ </rdf:Description>
+ </rdf:RDF>
+</x:xmpmeta>
+<?xpacket end="w"?>"#;
+
+/// Issue #92: saving merges into another app's sidecar instead of replacing it.
+#[test]
+fn saving_merges_into_another_apps_sidecar() {
+ let src = temp_dir("merge");
+ let lib = temp_dir("merge-lib");
+ write_png(&src.join("shot.png"), 1);
+ std::fs::write(src.join("shot.xmp"), OTHER_APP_SIDECAR).unwrap();
+ let mut s = Session::new().with_fs();
+ s.open_library(&lib, false).unwrap();
+ s.execute("library.import", &json!({"paths": [src.join("shot.png").to_string_lossy()]})).unwrap();
+ let id = only(&s);
+ s.execute("library.select", &json!({"ids": [id.0]})).unwrap();
+ s.execute("photo.rate", &json!({"rating": 5})).unwrap();
+ s.execute("photo.setMeta", &json!({"title": "Harbour", "keywords": ["boats"]})).unwrap();
+ s.execute("develop.set", &json!({"control": "effects.clarity", "value": 30})).unwrap();
+ let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+ assert_eq!(r["merged"][0], src.join("shot.xmp").to_string_lossy().as_ref(), "{r}");
+ let out = std::fs::read_to_string(src.join("shot.xmp")).unwrap();
+ // the other app's data, byte for byte
+ for part in [
+ "crs:Exposure2012=\"+0.65\"",
+ "other:Secret=\"keep me\"",
+ " <xmpMM:History>\n <rdf:Seq>\n <rdf:li stEvt:action=\"derived\" stEvt:parameters=\"converted from image/x-raw to image/png\"/>\n </rdf:Seq>\n </xmpMM:History>",
+ " <crs:ToneCurvePV2012>\n <rdf:Seq>\n <rdf:li>0, 0</rdf:li>\n <rdf:li>128, 140</rdf:li>",
+ ] {
+ assert!(out.contains(part), "lost {part:?}:\n{out}");
+ }
+ let d = lightcraft_meta::parse_xmp(&out).unwrap();
+ assert_eq!(d.metadata.rating, Some(5), "ours replaces theirs");
+ assert_eq!(d.metadata.title.as_deref(), Some("Harbour"));
+ assert_eq!(d.properties.get("crs:Version"), Some(&vec!["99.0".to_string()]));
+ let saved = s.catalog.photo(id).unwrap().develop.clone();
+ // reading it back restores our settings (lc:settings wins over crs:)
+ s.execute("develop.set", &json!({"control": "effects.clarity", "value": 0})).unwrap();
+ s.execute("photo.readMetadataFromFile", &json!({})).unwrap();
+ assert_eq!(s.catalog.photo(id).unwrap().develop, saved);
+ // saving again keeps one LightCraft description and the other app's data
+ s.execute("photo.rate", &json!({"rating": 3})).unwrap();
+ s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+ let again = std::fs::read_to_string(src.join("shot.xmp")).unwrap();
+ assert_eq!(again.matches("<rdf:Description").count(), 2, "{again}");
+ assert!(again.contains("other:Secret=\"keep me\"") && again.contains("crs:Exposure2012=\"+0.65\""));
+ assert_eq!(lightcraft_meta::parse_xmp(&again).unwrap().metadata.rating, Some(3));
+
+ // a sidecar that isn't XMP is kept as a backup before it is replaced
+ std::fs::write(src.join("shot.xmp"), b"<not xmp").unwrap();
+ let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+ let backup = r["backups"][0]["backup"].as_str().unwrap().to_string();
+ assert!(backup.contains("shot.xmp.bak-"), "{r}");
+ assert_eq!(std::fs::read(&backup).unwrap(), b"<not xmp");
+ assert_eq!(lightcraft_meta::parse_xmp(&std::fs::read_to_string(src.join("shot.xmp")).unwrap()).unwrap().metadata.rating, Some(3));
+ // … and another one never overwrites the first backup
+ std::fs::write(src.join("shot.xmp"), b"<still not xmp").unwrap();
+ let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+ let second = r["backups"][0]["backup"].as_str().unwrap().to_string();
+ assert_ne!(second, backup);
+ assert_eq!(std::fs::read(&backup).unwrap(), b"<not xmp");
+ assert_eq!(std::fs::read(&second).unwrap(), b"<still not xmp");
+ let _ = std::fs::remove_dir_all(&src);
+ let _ = std::fs::remove_dir_all(&lib);
+}
+
+/// Issue #92: two catalogued files with one stem (`IMG_1.jpg` + `IMG_1.png`) don't share a
+/// Stem-named sidecar: the first by name keeps `IMG_1.xmp`, the other writes and reads
+/// `IMG_1.png.xmp`.
+#[test]
+fn files_sharing_a_stem_get_their_own_sidecars() {
+ let src = temp_dir("stem");
+ let lib = temp_dir("stem-lib");
+ write_png(&src.join("IMG_1.png"), 1);
+ let img = lightcraft_raster::Rgba8::from_fn(40, 24, |x, y| [(x * 6) as u8, (y * 9) as u8, 7, 255]);
+ let jpg =
+ crate::export::encode_image(&img, &crate::export::ExportOptions { format: crate::export::ExportFormat::Jpeg, ..Default::default() }).unwrap();
+ std::fs::write(src.join("IMG_1.jpg"), jpg).unwrap();
+ let mut s = Session::new().with_fs();
+ s.open_library(&lib, false).unwrap();
+ s.execute("library.import", &json!({"paths": [src.to_string_lossy()]})).unwrap();
+ let id = |s: &Session, name: &str| s.catalog.photos().find(|p| p.file_name == name).unwrap().id;
+ let (j, p) = (id(&s, "IMG_1.jpg"), id(&s, "IMG_1.png"));
+ assert_eq!(s.sidecar_naming(j), crate::sidecar::SidecarNaming::Stem);
+ assert_eq!(s.sidecar_naming(p), crate::sidecar::SidecarNaming::Full);
+ s.execute("photo.rate", &json!({"ids": [j.0], "rating": 2})).unwrap();
+ s.execute("photo.rate", &json!({"ids": [p.0], "rating": 5})).unwrap();
+ let r = s.execute("photo.saveMetadataToFile", &json!({"ids": [j.0, p.0]})).unwrap();
+ assert_eq!(r["written"].as_array().unwrap().len(), 2, "{r}");
+ let rating = |f: &str| lightcraft_meta::parse_xmp(&std::fs::read_to_string(src.join(f)).unwrap()).unwrap().metadata.rating;
+ assert_eq!(rating("IMG_1.xmp"), Some(2));
+ assert_eq!(rating("IMG_1.png.xmp"), Some(5));
+ // each reads its own back
+ s.execute("photo.rate", &json!({"ids": [j.0, p.0], "rating": 0})).unwrap();
+ s.execute("photo.readMetadataFromFile", &json!({"ids": [j.0, p.0]})).unwrap();
+ assert_eq!((s.catalog.photo(j).unwrap().rating, s.catalog.photo(p).unwrap().rating), (2, 5));
+ let _ = std::fs::remove_dir_all(&src);
+ let _ = std::fs::remove_dir_all(&lib);
+}
diff --git a/crates/meta/src/lib.rs b/crates/meta/src/lib.rs
index 8f3e66c73..3408aed76 100644
--- a/crates/meta/src/lib.rs
+++ b/crates/meta/src/lib.rs
@@ -17,6 +17,7 @@ mod gpx;
mod iptc;
pub mod tags;
mod xmp;
+mod xmp_merge;
pub use container::{Embedded, embedded, jpeg_segments, png_chunks, webp_chunks};
pub use datetime::DateTime;
@@ -26,6 +27,7 @@ pub use iptc::parse_iptc;
pub use lightcraft_geom::Orientation;
pub use tags::{TagRow, file_tag_rows, tag_rows};
pub use xmp::{CRS_NS, LC_NS, XmpData, XmpError, XmpValue, parse_xmp, write_xmp, write_xmp_lc};
+pub use xmp_merge::{MergeRules, merge_xmp};
use serde::{Deserialize, Serialize};
diff --git a/crates/meta/src/xmp.rs b/crates/meta/src/xmp.rs
index 706976eb8..07373e62b 100644
--- a/crates/meta/src/xmp.rs
+++ b/crates/meta/src/xmp.rs
@@ -145,6 +145,11 @@ impl Node {
const MAX_DEPTH: usize = 64;
const MAX_NODES: usize = 200_000;
+/// `prefix:local` with the prefix canonicalised by namespace URI (see [`NAMESPACES`]).
+pub(crate) fn canonical_name(qname: &str, scopes: &[Vec<(String, String)>]) -> String {
+ canonical(qname, scopes)
+}
+
fn canonical(qname: &str, scopes: &[Vec<(String, String)>]) -> String {
let (prefix, local) = qname.split_once(':').unwrap_or(("", qname));
if prefix == "xml" || prefix == "xmlns" {
diff --git a/crates/meta/src/xmp_merge.rs b/crates/meta/src/xmp_merge.rs
new file mode 100644
index 000000000..6cbb6bdfc
--- /dev/null
+++ b/crates/meta/src/xmp_merge.rs
@@ -0,0 +1,403 @@
+//! Merging a freshly written XMP packet into an existing one (a sidecar another application
+//! wrote, e.g. with its develop settings and edit history), keeping everything the writer does not
+//! own byte for byte.
+//!
+//! The existing packet is scanned once (namespace-resolved, with byte positions). Only top-level
+//! properties of the `rdf:Description` elements directly under `rdf:RDF` are considered, in
+//! attribute form (`xmp:Rating="3"`) and element form (`<dc:subject>…</dc:subject>`):
+//! - properties the writer owns ([`MergeRules::owned`]) are removed, and written from the fresh
+//! packet when it has them (so a cleared field is cleared in the file too);
+//! - properties owned only when stated ([`MergeRules::owned_if_present`]) are replaced when the
+//! fresh packet has them and kept otherwise;
+//! - any other property of the fresh packet (e.g. `xmp:CreatorTool`) is not written: the file
+//! keeps describing itself as its creator left it;
+//! - everything else — other namespaces (e.g. `crs:`), `xmpMM:History`, unknown properties,
+//! comments, the packet wrapper and padding — is copied unchanged.
+//!
+//! The written properties go into one new `rdf:Description` (declaring its own namespaces, so
+//! the existing prefix bindings never matter) just before `</rdf:RDF>`. A description left empty
+//! by the removals is dropped, so repeated saves don't accumulate. The result is checked by
+//! parsing it again: every written property must read back as in the fresh packet.
+
+use std::collections::BTreeSet;
+
+use quick_xml::events::Event;
+
+use crate::xmp::{XmpError, canonical_name, parse_xmp};
+
+/// Which properties [`merge_xmp`] takes from the fresh packet. Names are canonical
+/// `prefix:name` (prefixes as [`crate::parse_xmp`] reports them); `prefix:*` is a whole namespace.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct MergeRules<'a> {
+ /// Always replaced: removed from the existing packet, written from the fresh one if stated.
+ pub owned: &'a [&'a str],
+ /// Replaced only when the fresh packet states them; otherwise the existing value stays.
+ pub owned_if_present: &'a [&'a str],
+}
+
+fn listed(list: &[&str], name: &str) -> bool {
+ list.iter().any(|p| match p.strip_suffix('*') {
+ Some(ns) => name.starts_with(ns),
+ None => *p == name,
+ })
+}
+
+#[derive(Debug)]
+struct Attr {
+ raw: String,
+ name: String,
+ /// The value as written (still escaped).
+ value: String,
+}
+
+#[derive(Debug)]
+struct Prop {
+ name: String,
+ start: usize,
+ end: usize,
+}
+
+#[derive(Debug, Default)]
+struct Desc {
+ tag_start: usize,
+ tag_end: usize,
+ /// The element name as written (`rdf:Description`, or another prefix for the RDF namespace).
+ raw_name: String,
+ empty: bool,
+ attrs: Vec<Attr>,
+ props: Vec<Prop>,
+ /// The end of `</rdf:Description>` (`tag_end` when self-closing).
+ end: usize,
+}
+
+#[derive(Debug, Default)]
+struct Scan {
+ descs: Vec<Desc>,
+ /// Where the first `</rdf:RDF>` starts.
+ rdf_close: Option<usize>,
+}
+
+enum Kind {
+ Other,
+ Rdf,
+ Desc(usize),
+ Prop { desc: usize, start: usize, name: String },
+}
+
+fn is_meta_attr(name: &str) -> bool {
+ name.starts_with("xmlns")
+ || matches!(name, "rdf:about" | "rdf:ID" | "rdf:nodeID" | "xml:lang" | "rdf:parseType" | "rdf:resource" | "rdf:datatype")
+}
+
+fn pos(r: &quick_xml::Reader<&[u8]>) -> usize {
+ usize::try_from(r.buffer_position()).unwrap_or(usize::MAX)
+}
+
+/// Locate the descriptions, their top-level properties and `</rdf:RDF>` in a packet.
+fn scan(s: &str) -> Result<Scan, XmpError> {
+ let mut reader = quick_xml::Reader::from_reader(s.as_bytes());
+ reader.config_mut().check_end_names = true;
+ let mut out = Scan::default();
+ let mut stack: Vec<Kind> = Vec::new();
+ let mut scopes: Vec<Vec<(String, String)>> = vec![vec![("xml".into(), "http://www.w3.org/XML/1998/namespace".into())]];
+ let mut count = 0usize;
+ loop {
+ let before = pos(&reader);
+ let ev = reader.read_event().map_err(|e| XmpError::Xml(e.to_string()))?;
+ let after = pos(&reader);
+ match ev {
+ Event::Start(ref e) | Event::Empty(ref e) => {
+ count += 1;
+ if count > 200_000 || stack.len() > 64 {
+ return Err(XmpError::TooComplex);
+ }
+ let empty = matches!(ev, Event::Empty(_));
+ let mut scope = Vec::new();
+ let mut raw_attrs = Vec::new();
+ for a in e.attributes() {
+ let a = a.map_err(|e| XmpError::Xml(e.to_string()))?;
+ let k = String::from_utf8_lossy(a.key.as_ref()).into_owned();
+ let v = String::from_utf8_lossy(&a.value).into_owned();
+ if k == "xmlns" {
+ scope.push((String::new(), v.clone()));
+ } else if let Some(p) = k.strip_prefix("xmlns:") {
+ scope.push((p.to_string(), v.clone()));
+ }
+ raw_attrs.push((k, v));
+ }
+ scopes.push(scope);
+ let raw_name = String::from_utf8_lossy(e.name().as_ref()).into_owned();
+ let name = canonical_name(&raw_name, &scopes);
+ let kind = match stack.last() {
+ Some(Kind::Rdf) if name == "rdf:Description" => {
+ let attrs = raw_attrs.into_iter().map(|(raw, value)| Attr { name: canonical_name(&raw, &scopes), raw, value }).collect();
+ out.descs.push(Desc { tag_start: before, tag_end: after, raw_name, empty, attrs, props: Vec::new(), end: after });
+ Kind::Desc(out.descs.len() - 1)
+ }
+ Some(Kind::Desc(i)) => Kind::Prop { desc: *i, start: before, name },
+ _ if name == "rdf:RDF" && out.rdf_close.is_none() => Kind::Rdf,
+ _ => Kind::Other,
+ };
+ if empty {
+ scopes.pop();
+ if let Kind::Prop { desc, start, name } = kind
+ && let Some(d) = out.descs.get_mut(desc)
+ {
+ d.props.push(Prop { name, start, end: after });
+ }
+ } else {
+ stack.push(kind);
+ }
+ }
+ Event::End(_) => {
+ scopes.pop();
+ match stack.pop() {
+ Some(Kind::Prop { desc, start, name }) => {
+ if let Some(d) = out.descs.get_mut(desc) {
+ d.props.push(Prop { name, start, end: after });
+ }
+ }
+ Some(Kind::Desc(i)) => {
+ if let Some(d) = out.descs.get_mut(i) {
+ d.end = after;
+ }
+ }
+ Some(Kind::Rdf) => out.rdf_close = out.rdf_close.or(Some(before)),
+ Some(Kind::Other) => {}
+ None => return Err(XmpError::Xml("unbalanced end tag".into())),
+ }
+ }
+ Event::Eof => break,
+ _ => {}
+ }
+ }
+ if !stack.is_empty() {
+ return Err(XmpError::Xml("unclosed element".into()));
+ }
+ Ok(out)
+}
+
+/// `start` moved back over the indentation and line break before it (so a removed property
+/// takes its line with it).
+fn line_start(s: &str, start: usize) -> usize {
+ let b = s.as_bytes();
+ let mut i = start;
+ while i > 0 && matches!(b.get(i - 1), Some(b' ' | b'\t')) {
+ i -= 1;
+ }
+ if i > 0 && b.get(i - 1) == Some(&b'\n') {
+ i -= 1;
+ if i > 0 && b.get(i - 1) == Some(&b'\r') {
+ i -= 1;
+ }
+ }
+ i
+}
+
+/// Merge `fresh` (a packet as [`crate::write_xmp_lc`] writes it) into `existing` following
+/// `rules` (see the module docs). Fails — and the caller must not overwrite `existing` blindly —
+/// when `existing` isn't a well-formed XMP packet.
+pub fn merge_xmp(existing: &str, fresh: &str, rules: MergeRules) -> Result<String, XmpError> {
+ let (bom, old) = match existing.strip_prefix('\u{feff}') {
+ Some(rest) => ("\u{feff}", rest),
+ None => ("", existing),
+ };
+ parse_xmp(old)?;
+ let ex = scan(old)?;
+ let rdf_close = ex.rdf_close.ok_or_else(|| XmpError::Xml("no rdf:RDF element".into()))?;
+ let new = scan(fresh)?;
+ let fresh_desc = new.descs.first().ok_or_else(|| XmpError::Xml("the new packet has no rdf:Description".into()))?;
+ let fresh_names: BTreeSet<&str> = fresh_desc.props.iter().map(|p| p.name.as_str()).collect();
+ let remove = |name: &str| listed(rules.owned, name) || (listed(rules.owned_if_present, name) && fresh_names.contains(name));
+ let write = |name: &str| listed(rules.owned, name) || listed(rules.owned_if_present, name);
+
+ // edits on `old`: (start, end, replacement), applied back to front
+ let mut edits: Vec<(usize, usize, String)> = Vec::new();
+ for d in &ex.descs {
+ let gone_attrs: Vec<&Attr> = d.attrs.iter().filter(|a| !is_meta_attr(&a.name) && remove(&a.name)).collect();
+ let gone_props: Vec<&Prop> = d.props.iter().filter(|p| remove(&p.name)).collect();
+ if gone_attrs.is_empty() && gone_props.is_empty() {
+ continue;
+ }
+ let attrs_left = d.attrs.iter().any(|a| !is_meta_attr(&a.name) && !remove(&a.name));
+ if !attrs_left && gone_props.len() == d.props.len() {
+ // nothing of its own left: drop the whole description
+ edits.push((line_start(old, d.tag_start), d.end, String::new()));
+ continue;
+ }
+ if !gone_attrs.is_empty() {
+ let mut tag = format!("<{}", d.raw_name);
+ for a in d.attrs.iter().filter(|a| is_meta_attr(&a.name) || !remove(&a.name)) {
+ tag.push_str(&format!("\n {}=\"{}\"", a.raw, a.value.replace('"', "&quot;")));
+ }
+ tag.push_str(if d.empty { "/>" } else { ">" });
+ edits.push((d.tag_start, d.tag_end, tag));
+ }
+ for p in gone_props {
+ edits.push((line_start(old, p.start), p.end, String::new()));
+ }
+ }
+ // the new description: its own namespace declarations, the properties to write
+ let mut block = String::from("\n <rdf:Description rdf:about=\"\"\n xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"");
+ for a in fresh_desc.attrs.iter().filter(|a| a.raw.starts_with("xmlns:") && a.raw != "xmlns:rdf") {
+ block.push_str(&format!("\n {}=\"{}\"", a.raw, a.value));
+ }
+ block.push('>');
+ let mut written = 0;
+ for p in fresh_desc.props.iter().filter(|p| write(&p.name)) {
+ let text = fresh.get(p.start..p.end).ok_or_else(|| XmpError::Xml("bad property span".into()))?;
+ block.push_str("\n ");
+ block.push_str(text);
+ written += 1;
+ }
+ block.push_str("\n </rdf:Description>");
+ if written > 0 {
+ let at = old.get(..rdf_close).map_or(rdf_close, |h| h.trim_end().len());
+ edits.push((at, at, block));
+ }
+ edits.sort_by_key(|e| (e.0, e.1));
+ // overlapping edits can't happen (properties sit inside their description, which is either
+ // dropped whole or edited piecewise), but never splice blindly
+ let mut out = String::with_capacity(old.len() + 4096);
+ out.push_str(bom);
+ let mut at = 0;
+ for (s, e, r) in &edits {
+ if *s < at {
+ return Err(XmpError::Xml("overlapping edits".into()));
+ }
+ out.push_str(old.get(at..*s).ok_or_else(|| XmpError::Xml("bad span".into()))?);
+ out.push_str(r);
+ at = *e;
+ }
+ out.push_str(old.get(at..).ok_or_else(|| XmpError::Xml("bad span".into()))?);
+
+ // read back: everything written must come out as written
+ let merged = parse_xmp(&out)?;
+ let want = parse_xmp(fresh)?;
+ for (k, v) in &want.properties {
+ let top = k.split('/').next().unwrap_or(k);
+ if write(top) && merged.properties.get(k) != Some(v) {
+ return Err(XmpError::Xml(format!("{k} did not survive the merge")));
+ }
+ }
+ Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const RULES: MergeRules =
+ MergeRules { owned: &["xmp:Rating", "xmp:Label", "dc:subject", "dc:title", "lc:*"], owned_if_present: &["exif:DateTimeOriginal"] };
+
+ /// A sidecar as another raw developer writes it: attribute-form simple properties, develop
+ /// settings, a structured history, an unknown namespace.
+ const FOREIGN: &str = "<?xpacket begin=\"\u{feff}\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>
+<x:xmpmeta xmlns:x=\"adobe:ns:meta/\" x:xmptk=\"Some Toolkit 1.0\">
+ <rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">
+ <rdf:Description rdf:about=\"\"
+ xmlns:xmp=\"http://ns.adobe.com/xap/1.0/\"
+ xmlns:xmpMM=\"http://ns.adobe.com/xap/1.0/mm/\"
+ xmlns:stEvt=\"http://ns.adobe.com/xap/1.0/sType/ResourceEvent#\"
+ xmlns:crs=\"http://ns.adobe.com/camera-raw-settings/1.0/\"
+ xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
+ xmlns:foo=\"http://example.com/foo/\"
+ xmp:Rating=\"2\"
+ xmp:CreatorTool=\"Other App\"
+ crs:Exposure2012=\"+0.50\"
+ crs:Contrast2012=\"-12\"
+ foo:Thing=\"a &amp; b\">
+ <xmpMM:History>
+ <rdf:Seq>
+ <rdf:li stEvt:action=\"saved\" stEvt:when=\"2026-01-02T03:04:05\"/>
+ </rdf:Seq>
+ </xmpMM:History>
+ <crs:ToneCurvePV2012>
+ <rdf:Seq>
+ <rdf:li>0, 0</rdf:li>
+ <rdf:li>255, 255</rdf:li>
+ </rdf:Seq>
+ </crs:ToneCurvePV2012>
+ <dc:subject>
+ <rdf:Bag>
+ <rdf:li>old</rdf:li>
+ </rdf:Bag>
+ </dc:subject>
+ </rdf:Description>
+ </rdf:RDF>
+</x:xmpmeta>
+";
+
+ /// With the packet's whitespace padding and trailer.
+ fn foreign() -> String {
+ format!("{FOREIGN}{}\n<?xpacket end=\"w\"?>", " ".repeat(100))
+ }
+
+ fn fresh(rating: i8, keywords: &[&str]) -> String {
+ let m = crate::Metadata {
+ software: Some("LightCraft".into()),
+ rating: Some(rating),
+ keywords: keywords.iter().map(|k| k.to_string()).collect(),
+ ..Default::default()
+ };
+ crate::write_xmp_lc(&m, &[("settings", "{\"a\":1}"), ("flag", "pick")])
+ }
+
+ #[test]
+ fn keeps_foreign_properties_and_replaces_owned_ones() {
+ let out = merge_xmp(&foreign(), &fresh(4, &["new", "two"]), RULES).unwrap();
+ let d = parse_xmp(&out).unwrap();
+ let p = |k: &str| d.properties.get(k).cloned().unwrap_or_default();
+ assert_eq!(p("xmp:Rating"), vec!["4"]);
+ assert_eq!(p("dc:subject"), vec!["new", "two"]);
+ assert_eq!(p("lc:settings"), vec!["{\"a\":1}"]);
+ assert_eq!(p("lc:flag"), vec!["pick"]);
+ assert_eq!(p("xmp:CreatorTool"), vec!["Other App"], "not ours: kept");
+ assert_eq!(p("crs:Exposure2012"), vec!["+0.50"]);
+ assert_eq!(p("foo:Thing").len(), 1);
+ // untouched parts are byte for byte the same
+ for part in [
+ " <xmpMM:History>\n <rdf:Seq>\n <rdf:li stEvt:action=\"saved\" stEvt:when=\"2026-01-02T03:04:05\"/>\n </rdf:Seq>\n </xmpMM:History>",
+ " <crs:ToneCurvePV2012>\n <rdf:Seq>\n <rdf:li>0, 0</rdf:li>",
+ "crs:Contrast2012=\"-12\"",
+ "foo:Thing=\"a &amp; b\"",
+ "<?xpacket begin=\"\u{feff}\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>\n<x:xmpmeta xmlns:x=\"adobe:ns:meta/\" x:xmptk=\"Some Toolkit 1.0\">",
+ &format!("</x:xmpmeta>\n{}\n<?xpacket end=\"w\"?>", " ".repeat(100)),
+ ] {
+ assert!(out.contains(part), "lost {part:?} in\n{out}");
+ }
+ assert!(!out.contains("xmp:Rating=\"2\""));
+ assert!(!out.contains("<rdf:li>old</rdf:li>"));
+ // saving again changes only our part, and doesn't pile up descriptions
+ let again = merge_xmp(&out, &fresh(1, &[]), RULES).unwrap();
+ let d = parse_xmp(&again).unwrap();
+ assert_eq!(d.properties.get("xmp:Rating"), Some(&vec!["1".to_string()]));
+ assert!(!d.properties.contains_key("dc:subject"), "a cleared field is cleared");
+ assert_eq!(again.matches("<rdf:Description").count(), 2, "{again}");
+ assert_eq!(merge_xmp(&again, &fresh(1, &[]), RULES).unwrap(), again, "idempotent");
+ }
+
+ #[test]
+ fn owned_if_present_and_prefix_independence() {
+ // the existing packet binds the namespaces to other prefixes, and has a capture time
+ let ex = "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><r:RDF xmlns:r=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">\
+ <r:Description r:about=\"\" xmlns:a=\"http://ns.adobe.com/xap/1.0/\" xmlns:e=\"http://ns.adobe.com/exif/1.0/\" \
+ a:Rating=\"5\" e:DateTimeOriginal=\"2020-01-01T00:00:00\"/></r:RDF></x:xmpmeta>";
+ let out = merge_xmp(ex, &fresh(3, &[]), RULES).unwrap();
+ let d = parse_xmp(&out).unwrap();
+ assert_eq!(d.properties.get("xmp:Rating"), Some(&vec!["3".to_string()]));
+ assert_eq!(d.properties.get("exif:DateTimeOriginal"), Some(&vec!["2020-01-01T00:00:00".to_string()]), "fresh has none: kept");
+ let mut m = crate::Metadata { rating: Some(3), ..Default::default() };
+ m.capture_time = crate::DateTime::parse_iso("2024-05-06T07:08:09");
+ let out = merge_xmp(ex, &crate::write_xmp_lc(&m, &[]), RULES).unwrap();
+ let d = parse_xmp(&out).unwrap();
+ assert_eq!(d.properties.get("exif:DateTimeOriginal"), Some(&vec!["2024-05-06T07:08:09".to_string()]));
+ }
+
+ #[test]
+ fn refuses_what_it_cannot_read() {
+ for bad in ["", "not xml at all", "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><rdf:RDF", "<a><b></a>", "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"/>"] {
+ assert!(merge_xmp(bad, &fresh(1, &[]), RULES).is_err(), "{bad:?}");
+ }
+ }
+}
diff --git a/crates/meta/tests/robust.rs b/crates/meta/tests/robust.rs
index 679fc49dc..6386e7009 100644
--- a/crates/meta/tests/robust.rs
+++ b/crates/meta/tests/robust.rs
@@ -1,4 +1,4 @@
-use lightcraft_meta::{Metadata, extract, parse_iptc, parse_xmp, read_exif, write_xmp};
+use lightcraft_meta::{MergeRules, Metadata, extract, merge_xmp, parse_iptc, parse_xmp, read_exif, write_xmp};
use proptest::prelude::*;
proptest! {
@@ -21,6 +21,23 @@ proptest! {
let _ = parse_xmp(&s);
}
+ /// Merging into arbitrary (also damaged) packets never panics, and a merge that succeeds
+ /// reads back with the written values.
+ #[test]
+ fn merge_never_panics(cut in 0usize..900, junk in ".{0,20}", rating in 0i8..=5) {
+ let base = write_xmp(&Metadata { title: Some("t".into()), rating: Some(1), ..Default::default() }, Some("{}"));
+ let mut s: String = base.chars().take(cut).collect();
+ s.push_str(&junk);
+ s.extend(base.chars().skip(cut));
+ let fresh = write_xmp(&Metadata { rating: Some(rating), ..Default::default() }, Some("{\"x\":1}"));
+ let rules = MergeRules { owned: &["xmp:Rating", "dc:title", "lc:*"], owned_if_present: &[] };
+ if let Ok(out) = merge_xmp(&s, &fresh, rules) {
+ let d = parse_xmp(&out).unwrap();
+ prop_assert_eq!(d.metadata.rating, Some(rating));
+ prop_assert_eq!(d.lc_settings.as_deref(), Some("{\"x\":1}"));
+ }
+ }
+
#[test]
fn user_text_roundtrips(title in "[a-zA-Z0-9 &<>\"'éü€;|/\\\\]{1,40}", kw in proptest::collection::vec("[a-zA-Z0-9 &<>\"'|]{1,12}", 0..5), rating in -1i8..=5) {
let title = title.trim().to_string();
diff --git a/docs/parity.md b/docs/parity.md
index b8f0e30cc..61da28756 100644
--- a/docs/parity.md
+++ b/docs/parity.md
@@ -210,7 +210,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins.
| LR-META-COPYRIGHT-DEFAULT | Default copyright on import | P1 | ✅ | `cmd:library.preferences` (`import.copyright`, `import.creator`), `crates/ui-egui/src/panels/settings.rs` | Settings → Import → Metadata; fills only photos without their own |
| LR-META-LOCATION | Location editing | P2 | 🟡 | `cmd:photo.setMeta` (`location`, `city`, `state`, `country`, `gps`) | place fields and GPS (decimal or degrees / minutes / seconds) edited in Info, read/written as IPTC Core / Photoshop / EXIF XMP; Show on Map opens OpenStreetMap; no embedded map, no geocoding |
| LR-META-COPYPASTE | Copy / paste metadata | P2 | ✅ | `cmd:photo.copyMetadata`, `cmd:photo.pasteMetadata` | title, caption, alt text, extended description, copyright (notice, status, usage terms, info URL), creator, place fields, keywords; `fields` picks a subset |
-| LR-META-XMP | XMP read/write | P0 | ✅ | `cmd:photo.saveMetadataToFile`, `cmd:photo.readMetadataFromFile`, `cmd:library.xmpPreferences`, `crates/engine/src/sidecar.rs`, `docs/xmp-interop.md` | sidecar wins for metadata; a sidecar capture time (`exif:DateTimeOriginal` / `photoshop:DateCreated` / `xmp:CreateDate`) fills in only when the file has none |
+| LR-META-XMP | XMP read/write | P0 | ✅ | `cmd:photo.saveMetadataToFile`, `cmd:photo.readMetadataFromFile`, `cmd:library.xmpPreferences`, `crates/engine/src/sidecar.rs`, `docs/xmp-interop.md` | sidecar wins for metadata; a sidecar capture time (`exif:DateTimeOriginal` / `photoshop:DateCreated` / `xmp:CreateDate`) fills in only when the file has none; saving merges into an existing sidecar (`crates/meta/src/xmp_merge.rs`): another app's `crs:`, `xmpMM:History` and unknown namespaces are kept byte for byte, an unreadable sidecar is backed up first; with stem naming, files sharing a stem (raw + JPEG) get separate sidecars (`<file>.xmp` for all but the raw) |
| LR-META-EXIF-FULL | Full EXIF/IPTC [Classic] | P1 | ✅ | `cmd:photo.allMetadata`, `cmd:dialog.allMetadata`, `crates/meta/src/tags.rs`, `crates/meta/src/exif.rs`, `crates/meta/src/iptc.rs` | read and written on export; Info ▸ All Metadata…: every TIFF / EXIF / GPS / interop tag (named, common values spelled out) and the XMP fields, searchable; metadata presets |
## F. Edit panel — global adjustments (EDIT)
diff --git a/docs/whats-new.md b/docs/whats-new.md
index dbbadf900..e46584c9d 100644
--- a/docs/whats-new.md
+++ b/docs/whats-new.md
@@ -10,6 +10,11 @@
- 23 new built-in presets: Portrait, Landscape, Urban, Food, Seasons, Vintage and B&W toners.
### Reliability
+- Saving metadata to an XMP sidecar another application wrote no longer replaces it (issue #92): LightCraft merges its
+ fields in and keeps the rest — e.g. that application's develop settings and edit history — byte for byte. A
+ sidecar that isn't valid XMP is copied to `<name>.xmp.bak-<time>` first. With the default stem naming, a raw and a
+ JPEG with the same name (`IMG_0001.CR3` + `IMG_0001.JPG`) no longer share one sidecar: the raw keeps `IMG_0001.xmp`,
+ the JPEG uses `IMG_0001.JPG.xmp`.
- Canon CR2 photos from the EOS 7D, 50D, 60D, 550D, 600D, 1200D, 1300D, 5D Mark II and 1D Mark IV (and other
models whose sensor starts on a green-blue row) no longer come out magenta (issue #85): the colour-filter
layout is read from each file instead of assumed.
diff --git a/docs/xmp-interop.md b/docs/xmp-interop.md
index 7332b9ce8..017f35691 100644
--- a/docs/xmp-interop.md
+++ b/docs/xmp-interop.md
@@ -8,8 +8,8 @@ other tools), and let LightCraft pick up edits made elsewhere.
| | |
|---|---|
-| Name | `<stem>.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `<file>.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. |
-| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. Written atomically (temp file + rename). |
+| Name | `<stem>.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `<file>.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. With stem naming, files sharing a stem don't share a sidecar: see *Shared names* below. |
+| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. An existing sidecar is **merged into, never replaced** (see *Saving into an existing sidecar*). Written atomically (temp file, fsync, rename). The result lists `written`, `merged` and `backups`. |
| Read | On import (`library.import`, the report counts `sidecars`), and `photo.readMetadataFromFile {ids?}` (one undo step). For raw/DNG files without a sidecar, the XMP embedded in the file is used. |
| Preferences | `library.xmpPreferences {autoWrite?, naming?: stem\|full}`, stored in the library's `prefs.json`. |
@@ -37,6 +37,39 @@ used — on import (it then also files a copied photo in its date folder) and by
`xmp:Rating="-1"` (the XMP convention for rejected) sets the reject flag. Develop settings come from
`lc:settings` when present (exact); otherwise from the `crs:` fields below (approximate).
+## Saving into an existing sidecar
+
+A sidecar may already hold another application's data — e.g. its `crs:` develop settings and `xmpMM:History` — often
+the only copy of those edits outside that application's catalog. Saving never drops it:
+
+- LightCraft **owns** the properties in the table above: `xmp:Rating`, `xmp:Label`, `dc:title`, `dc:description`,
+ `dc:rights`, `dc:creator`, `dc:subject`, `Iptc4xmpCore:Location`, `Iptc4xmpCore:AltTextAccessibility`,
+ `Iptc4xmpCore:ExtDescrAccessibility`, `photoshop:City`/`State`/`Country`, `xmpRights:Marked`/`UsageTerms`/
+ `WebStatement` and everything in `lc:`. They are replaced on every save, and removed when LightCraft has no value
+ (clearing a title in LightCraft clears it in the file). All of them are read back on import, so the library starts
+ from what the sidecar said.
+- The **capture time** (`exif:DateTimeOriginal`, `photoshop:DateCreated`) and **GPS** (`exif:GPSLatitude`,
+ `exif:GPSLongitude`) are replaced only when LightCraft has a value; otherwise the file's stay.
+- **Everything else is kept byte for byte**: other namespaces (`crs:`, `xmpMM:`, `lr:hierarchicalSubject`, unknown
+ ones), `xmp:CreatorTool`, comments, the packet wrapper and padding. LightCraft's properties go into one
+ `rdf:Description` of their own; owned properties written by another application (in attribute or element form) are
+ removed from its description, which otherwise stays as it was.
+- A sidecar that can't be read as XMP (not well-formed, not UTF-8, no `rdf:RDF`) is first copied to
+ `<name>.xmp.bak-<date><time>` (`-1`, `-2`… if taken — a backup is never overwritten), then replaced. A sidecar that
+ can't be read at all (permissions) is left alone and the save fails.
+
+Limits: LightCraft writes keywords to `dc:subject` only, so another application's `lr:hierarchicalSubject` is kept as
+it was and may still list keywords removed in LightCraft. LightCraft doesn't write `crs:`: the other application's
+develop settings stay as that application left them, next to LightCraft's own (`lc:settings`, which LightCraft reads
+first).
+
+## Shared names
+
+With stem naming, `IMG_0001.CR3` and `IMG_0001.JPG` map to the same `IMG_0001.xmp`. When two or more files in the
+library share a stem, the stem sidecar belongs to one of them — a raw first, otherwise the first by file name — and
+the others write and read `<file>.xmp` (`IMG_0001.JPG.xmp`), falling back to the stem sidecar for reading when they
+have none. So saving one photo never overwrites the other's metadata (`Session::sidecar_naming`).
+
## Reading `crs:` develop fields
Many raw developers store edits as `crs:` properties (`http://ns.adobe.com/camera-raw-settings/1.0/`) in sidecars, in