From 7c50f95fde8e38563f459a61751fd1dd31f877fb Mon Sep 17 00:00:00 2001
From: Jan Petykiewicz <jan@mpxd.net>
Date: Wed, 1 Apr 2026 20:00:46 -0700
Subject: [PATCH] [ILibrary] update docs for add()

---
 masque/library.py           |  4 ++--
 masque/test/test_library.py | 12 ++++++++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/masque/library.py b/masque/library.py
index 88799ec..825dbf0 100644
--- a/masque/library.py
+++ b/masque/library.py
@@ -923,8 +923,8 @@ class ILibrary(ILibraryView, MutableMapping[str, 'Pattern'], metaclass=ABCMeta):
                 (default).
 
         Returns:
-            A mapping of `{old_name: new_name}` for all `old_name`s in `other`. Unchanged
-            names map to themselves.
+            A mapping of `{old_name: new_name}` for all names in `other` which were
+            renamed while being added. Unchanged names are omitted.
 
         Raises:
             `LibraryError` if a duplicate name is encountered even after applying `rename_theirs()`.
diff --git a/masque/test/test_library.py b/masque/test/test_library.py
index e66b7cc..3b731ad 100644
--- a/masque/test/test_library.py
+++ b/masque/test/test_library.py
@@ -280,6 +280,18 @@ def test_library_add_no_duplicates_respects_mutate_other_false() -> None:
     assert tuple(src_pat.ports["A"].offset) == (0.0, 0.0)
 
 
+def test_library_add_returns_only_renamed_entries() -> None:
+    lib = Library({"a": Pattern(), "_shape": Pattern()})
+
+    assert lib.add({"b": Pattern(), "c": Pattern()}, mutate_other=False) == {}
+
+    rename_map = lib.add({"_shape": Pattern(), "keep": Pattern()}, mutate_other=False)
+
+    assert set(rename_map) == {"_shape"}
+    assert rename_map["_shape"] != "_shape"
+    assert "keep" not in rename_map
+
+
 def test_library_subtree() -> None:
     lib = Library()
     lib["a"] = Pattern()