Multiple active layers + Layer.merge() = Confusion

I’m looking for the right way to merge multiple layers at once. The description for Layer.merge() in the documentation says the following (see here):

Merges layers. This operates on the currently selected layers. If multiple layers are selected, they will be merged together. If one layer is selected, it is merged down with the layer beneath. In this case, the layer below must be a pixel layer. The merged layer will now be the active layer.

So it sounds like Layer.merge() should do two different things depending on how many layers are selected:

  1. With only one layer selected, the result is the equivalent to ‘Merge Down’, ie, the selected layer gets merged with the layer beneath it.
  2. With more than one layer selected, the result is equivalent to ‘Merge Layers’, ie, the selected layers only are merged together.

Layer.merge() works as expected for case #1 above (a single layer), but for case #2, it doesn’t. Consider the following starting point with 3 selected layers:


After running Layer.merge(), I end up with this:


So, essentially Layer.merge() is ignoring the fact that multiple layers are selected, and is just doing scenario #1 from above (ie, ‘Merge Down’) with the bottommost selected layer. I would expect the result instead to be like this:


Am I misunderstanding this? BTW, I’m invoking Layer.merge() like this:

await app.activeDocument.activeLayers[0].merge();

which is why the bottommost selected layer (“Layer 2” in my example = activeLayers[0]) is merged down with “Layer 1”. Invoking merge() instead from one of the other selected layers will cause that layer to be merged down with the layer beneath it. It kind of seems like merging multiple layers with Layer.merge() is not actually functional.

I can merge multiple layers successfully with BatchPlay, of course, but just wondered why Layer.merge() is not behaving as expected.