Try: Adding "clip" parameters

[deBhal]

We'd like to use mShots to dynamically generate preview screenshots in wordpress.com/new and it's looking great in general but there are a few themes that look pretty odd (see Automattic/wp-calypso#43428).

This PR is to discuss enabling more parameters for mshots to solve those problems.

I'm just dumping exploratory code here, but if I can get some agreement that this is the right way to go I'll tidy this up and extend the changes up to the API.

I'm working on OSX, so I don't have the kernel extensions required to run the mshots service, so I've just been running the snapshot lib directly. After cloning mshots into /opt/local and running npm install as per the instructions, I've been testing using:

node --experimental-repl-await
snapshot = require('./lib/snapshot')
await snapshot.init_browser()
test_url = 'https://public-api.wordpress.com/rest/v1/template/demo/rockfield/rockfield?font_headings=Playfair%20Display&font_base=Fira%20Sans&site_title=Rockfield'
// shim because snapshot expects to be a child process
process.send = process.send || ((...args) => console.log(...args))
snapshot.add_to_queue( { width: 1200, height: 3072, url: test_url, file: 'test.jpg', })

This takes a moment before it dumps the reply object, and then you can open /opt/mshots/test.jpg to see the image.

In particular, I've been looking at the Rockfield theme. It's got that cool effect where the background images change as the text wipes through them:

Unfortunately, the theme gets a bit confused when the viewport is big enough to get an impression of the theme:

snapshot.add_to_queue( { width: 1200, height: 3072, url: test_url, file: 'test.jpg', })

Each picture is being scaled to fill the entire scrollHeight, instead of the smaller viewport we'd see while scrolling through, so the first picture ends up being a picture of a giant hand

Now, there is an argument to be made that we could/should fix the css, but it's not really just another screen size to push on designers because we want different behaviour for this one, so I spent some time seeing if I could persuade puppeteer to play nice, and I found the clip parameter:
snapshot.add_to_queue( { width: 1200, height: 800, url: test_url, file: 'test.jpg', clip: { x:0, y:0, width:1200, height:3072 } } )

You can see that this is not perfect, as there's no image behind "Discover Our Menu", but it seems much better to me in this specific instance, and much more intuitive in general - we can keep the viewport parameters in typical sane ranges and use the clip parameters to "scroll down" instead.

I also checked out the 'fullPage' option, but it wasn't what I needed, but I saw someone ask for it so I thought I'd include it here (fullPage overrides both viewport and clip):

snapshot.add_to_queue( { fullPage: true, url: test_url + '&viewport_height=700', file: 'test.jpg' } )

Note that here we need the preview viewport hack on the website itself to get halfway reasonable result, otherwise the whole picture is just the giant hand with a little text at the bottom. I think the fact that we don't need that hack if we use the clip parameters instead is a really good sign that it's the right way to go.

[simison]

Would be cool to get tests in first so that we we can have more confidence in not regressing anything: #17

[deBhal]

#18 Covers this and includes the necessary PHP changes as well, so let's go with that.