M3.78: Recolor Artwork with colour reduction, methods, presets and Limit to Library

Recolor Artwork keys colours by identity (model and exact values), so CMYK
colours stay CMYK and lookalikes stay apart. recolor.reduce groups the
selection's colours into rows (k-means in Lab, weighted by use; tints of a
global swatch share its row) with Preserve White/Black/Grays and Limit to
Library; recolor.apply maps rows by Exact, Preserve Tints, Scale Tints, Tints
and Shades or Hue Shift; recolor.randomize shuffles or varies new colours.
The dialog has Assign (rows with merge, separate, exclude, randomize, method,
library) and Edit (hue/saturation wheel with linked or unlinked handles,
brightness, harmony rules) tabs, and Edit Colors gains Recolor with Preset
(1/2/3 Color Job, Color Library). Colour parameters accept colour keys.

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

docs/control-protocol.md

@@ -82,6 +82,13 @@ canvas while open; `ui.dialog.confirm` keeps the result as one undo step (`edit.
 `edit.colors.saturate`) and `ui.dialog.cancel` rolls it back. Global mode answers with an error until tints of global
 and spot colours exist; the dialog then stays open.
 
+Recolor Artwork: `ui.recolorDialog {colors?, library?}` opens the `recolor` dialog on the selected art (`colors`: a
+count for an n-colour job, or colours to assign as the new colours; `library`: Limit to Library, `""` for the first).
+Fields: `rows` (`[{from: [keys], to: key, exclude?}]` as `recolor.reduce` returns them), `colors` (null for Auto),
+`method`, `preserveWhite`, `preserveBlack`, `preserveGrays`, `limitTo`, `tab` (`assign` or `edit`), `rule` (harmony
+id), `linked`, `preview`. Setting `colors`, a preserve flag or `limitTo` reduces the rows again (also on
+`ui.dialog.confirm`). The dialog previews `recolor.apply` on the canvas; confirm keeps it as one undo step.
+
 Library panel: `engine.execute {command: "window.swatchLibrary", params: {library}}` opens the read-only library
 panel on a swatch library (`ui.inspect` shows it as `library_panel: {kind, id}`; `library: null` closes it).
 Clicking a swatch there runs `swatch.library.add {library, names: [name], apply}` (the active proxy, or the other

docs/mcp.md

@@ -317,6 +317,24 @@ patterns out. The Blend commands also grade gradient meshes, which keep their sh
 {"name":"run_command","arguments":{"command":"edit.colors.adjustBalance","params":{"mode":"cmyk","m":-20,"k":10}}}
 ```
 
+Recolor Artwork keys colours by identity, not hex: `recolor.colors` lists each colour's `key` (`"rgb 255 0 0"`,
+`"cmyk 0 100 100 0"`, `"gray 40"`, `"lab 55 60 -40"`; RGB in 0–255 levels, CMYK and Gray in percent), so CMYK,
+Lab and RGB colours that look alike stay apart, and every colour parameter also accepts a key. `recolor.reduce {colors?, method?,
+preserve?, limitTo?}` groups the selection's colours into rows of similar colours (k-means in Lab, weighted by use;
+tints of a global swatch share its row; White and Black are preserved by default) and returns a map of rows
+`[{from: [keys], to: key}]` to edit and pass to `recolor.apply {map, method?, limitTo?}`.
+`method` says how a row's colours take its new colour: `exact`, `preserveTints` (tints of the row's darkest colour
+stay tints), `scaleTints` (every colour becomes a tint as light, relative to the darkest), `tintsShades` (lighter and
+darker than the row's average become tints and shades) or `hueShift` (the most saturated colour takes the new colour,
+the others turn by the same hue). `limitTo` snaps new colours to a swatch library's nearest colour;
+`recolor.randomize {map, order?, saturationBrightness?, seed?}` shuffles or varies new colours; a row with
+`exclude: true` keeps its colours.
+
+```json
+{"name":"run_command","arguments":{"command":"recolor.reduce","params":{"colors":2,"preserve":{"grays":true}}}}
+{"name":"run_command","arguments":{"command":"recolor.apply","params":{"map":[{"from":["cmyk 0 100 100 0","cmyk 0 40 40 0"],"to":"cmyk 100 50 0 0"}],"method":"scaleTints"}}}
+```
+
 ## Group, layer and type appearance
 
 Groups and layers carry fills, strokes and effects of their own, as in the reference app: their fills and strokes