.flip() doesn't work after .composite()

[thot-experiment]

Possible bug

System Info

System:
OS: Windows 10 10.0.19044
CPU: (12) x64 Intel(R) Core(TM) i7-8700K CPU @ 3.70GHz
Memory: 13.38 GB / 31.95 GB
Binaries:
Node: 22.11.0 - C:\Program Files\nodejs\node.EXE
npm: 10.9.0 - C:\Program Files\nodejs\npm.CMD
npmPackages:
sharp: ^0.33.5 => 0.33.5

What are the steps to reproduce?

import sharp from 'sharp'

//background image
const width = 1024
const height = 1024
const channels = 4
const bg_data = new Uint8Array(width*height*channels)
const bg_sharp = await sharp(bg_data, {raw: {width,height,channels}})

//foreground image
const fg_data = new Uint8Array(width/2*height/2*channels).fill(255)

await bg_sharp
  .composite([
    {
      input: fg_data, 
      raw: {
        width:width/2,
        height:height/2,
        channels 
      },
      left:0,
      top:0
    }
  ])
  .flip()
  .toFile('output.png')

What is the expected behaviour?

The expectation here is that we get a transparent PNG with it's lower left quarter containing a white square, instead I get a non-flipped PNG with the upper left quarter containing a white square.

I see that in the documentation it's noted that This operation does not work correctly with multi-page images. but I don't think that's what's happening here?

[lovell]

Hello, you'll need to split this into two pipelines, one to composite and a second to flip.

This is alluded to in the docs (but perhaps could be made clearer to include flip/flop):

https://sharp.pixelplumbing.com/api-composite

Any resize, rotate or extract operations in the same processing pipeline will always be applied to the input image before composition.

[thot-experiment]

Hello, you'll need to split this into two pipelines, one to composite and a second to flip.

Ah, yeah thanks, no problem, I was already doing so but figured this wasn't expected.

(but perhaps could be made clearer to include flip/flop)

Yeah I think so, I did look but it didn't click for me that flip/flop was included. Just so I can have a better mental model, what is the reason for these operations being order dependent? What class of operations should I expect to be broken by having a .composite in the pipeline.

I'd be happy to send a pull against the docs once I have a good understanding of how this works/is supposed to work.

[lovell]

Almost all operations occur before image composition, which takes place near the end of the pipeline. (If you want the gory details there's some discussion at #241.)

I've reworded the docs a little via commit 82dc859 to help clarify.