M4.22: pasting between documents carries the objects' resources

Copy keeps the copied objects with every document resource they use
(Session.clipboard: Clipboard {nodes, images, symbols, patterns,
swatches, graphic_styles, char_styles, para_styles, brushes,
source_artboard, source_layers, source_doc}), following symbols,
patterns, graphic styles and text styles into what they use. Every
edit.paste* brings them in within its undo step: identical resources are
reused, missing ones added, different ones of the same name added
renamed (an earlier paste's copy is reused) and the pasted objects
relinked, graphic style links by id. Global and spot swatches that
conflict ask Merge or Add (swatchConflict; clipboard.conflicts lists
them; the app's Swatch Conflict dialog asks one by one, with Apply to
All). Tint swatches, linked gradient stops, Lab spots and the target's
Spot Colors option are honoured; [Registration] is never copied.
Clipboard SVG exports them too.

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

docs/control-protocol.md

@@ -226,3 +226,10 @@ Video, Art & Illustration, Branding, Social), `advanced` (Advanced Options open)
 changing a field afterwards makes the settings custom (`preset` becomes ""). More Settings is the `newDocumentMore`
 dialog over the same fields (its Profile is `category`). `ui.dialog.confirm` runs `file.new` with the fields (with
 `previewMode: "pixel"` the app turns Pixel Preview on); on an error the dialog stays open.
+
+Swatch Conflict: through the app, when the pasted objects' global or spot swatches conflict with the document's
+(see `clipboard.conflicts`) and the params have no `swatchConflict`, every Paste command opens the `swatchConflict`
+dialog instead and answers `{dialog: "swatchConflict"}`. Fields: `conflicts` (`[{name, document, clipboard,
+spot}]`), `index` (the conflict asked about), `choice` (`merge` or `add`), `applyToAll` and `choices` (the answers so
+far). `ui.dialog.confirm` records the answer and asks about the next conflict (with `applyToAll`, answers the rest
+the same); the last one runs the paste with `swatchConflict`. `ui.dialog.cancel` pastes nothing.

docs/mcp.md

@@ -863,3 +863,25 @@ with `pointer_gesture` (a click places at 100% with the top-left corner there, a
 {"name":"run_command","arguments":{"command":"file.place.queue","params":{"paths":["/tmp/a.png","/tmp/b.pdf"]}}}
 {"name":"pointer_gesture","arguments":{"events":[{"kind":"down","x":40,"y":40},{"kind":"up","x":40,"y":40}]}}
 ```
+
+## Copy and paste between documents
+
+`edit.copy` keeps the copied objects with the document resources they use: image blobs, symbols, patterns, global
+and spot swatches (with the tint swatches of the tints used; never the built-in [Registration] swatch), the gradient
+swatches their gradients came from, graphic styles the objects are linked to, character and paragraph styles and
+brushes. Width profiles live in the preferences, so they need no copying. Every `edit.paste*` command (also `edit.pasteWithoutFormatting`, which leaves
+text styles behind) brings them into the active document in the same undo step: an identical resource is reused,
+a missing one added, and one of the same name that differs is added renamed ("Mark 2"; a copy an earlier paste
+added is reused), which the pasted objects follow. Linked colours show the document's swatch at their tint (a Lab
+spot colour as its Spot Colors option says). The result reports `{ids, added, merged, renamed: [{kind, from,
+to}]}`.
+
+A global or spot swatch whose name the document gives another colour is a conflict: `clipboard.conflicts` lists
+them, and `swatchConflict` answers: `"merge"` (the default: the objects take the document's swatch), `"add"` (the
+pasted swatch comes in renamed) or one answer per name. Pasting back into the document the objects came from uses
+its resources as they are now and raises no conflict.
+
+```json
+{"name":"run_command","arguments":{"command":"clipboard.conflicts","params":{}}}
+{"name":"run_command","arguments":{"command":"edit.paste","params":{"swatchConflict":{"Brand":"add"}}}}
+```