Recipes#
Short, runnable examples. Every one of them was executed before it was written down.
One screenshot for a README#
pnpm cli screenshot.png --ratio 16:9 --scale 2Nothing else needed: the frame, the background and its colours all come from the screenshot itself.
A whole folder in one command#
pnpm cli docs/raw/*.png --style docs --out-dir docs/images --format pngThe shell expands the glob, and each image is rendered and written on its own. --style keeps the whole set consistent — see Styles.
A landing hero#
pnpm cli app.png --frame macbook --rotate-y -14 --ratio 16:9 --scale 3 --padding 0.09--rotate-y tilts the window; layers tilt with it. Past ±16° the redaction sampler drifts slightly, so keep annotations modest on a strongly tilted shot.
The same background, every time#
pnpm cli screenshot.png --seed 42The background is generated from a seeded PRNG. The same seed gives the same image down to the pixel, which is what you want when a doc is regenerated in CI and you do not want a noisy diff. Drop the seed and you get a new one each run.
Hide a secret#
{
"shots": [
{
"input": "dashboard.png",
"layers": [
{ "kind": "redaction", "redaction": "blur", "rect": { "x": 0.10, "y": 0.22, "w": 0.30, "h": 0.03 } },
{ "kind": "redaction", "redaction": "solid", "rect": { "x": 0.62, "y": 0.71, "w": 0.22, "h": 0.04 } }
]
}
]
}pnpm cli --spec redact.jsonblur and pixel sample the pixels underneath; solid covers them flat. All three are baked into the exported pixels, so what they hide is genuinely gone from the file — not merely covered by a filter someone could peel off. Keep the default "redactionShape": "rect" over text: an ellipse leaves the corners of its box untouched.
Point at something#
Get the frame first, then place the layers.
pnpm cli inspect signup.png --frame browser --json
# {"imageWidth":2880,"imageHeight":1800,"screen":{"x":0,"y":0.035,"w":1,"h":0.625},"source":{"x":0,"y":0,"w":2880,"h":1800},…}{
"settings": { "frame": "browser" },
"shots": [
{
"input": "signup.png",
"layers": [
{ "kind": "box", "rect": { "x": 0.0694, "y": 0.1392, "w": 0.4167, "h": 0.2431 } },
{ "kind": "arrow", "rect": { "x": 0.62, "y": 0.10, "w": -0.14, "h": 0.06 } },
{ "kind": "text", "text": "Start here", "rect": { "x": 0.63, "y": 0.09 } }
]
}
]
}The arrow's negative w makes it point down-left. The maths behind those numbers is in Coordinates.
Number the steps#
{
"shots": [
{
"input": "flow.png",
"layers": [
{ "kind": "badge", "rect": { "x": 0.08, "y": 0.16 } },
{ "kind": "badge", "rect": { "x": 0.41, "y": 0.33 } },
{ "kind": "badge", "rect": { "x": 0.74, "y": 0.52 } }
]
}
]
}A badge shows its rank among the badges of that shot — 1, 2, 3 in reading order of the array. The number is never stored, so reordering the array renumbers them.
Two screenshots, one visual#
{
"settings": { "ratio": "16:9", "seed": 7 },
"composition": { "layout": "side", "spread": 0.7 },
"shots": [{ "input": "before.png" }, { "input": "after.png" }]
}layout also takes stack and tilt3d. Layers stay attached to their own shot, and each shot keeps its own coordinate frame.
Add a logo#
{
"shots": [{ "input": "screenshot.png" }],
"watermark": { "path": "brand/logo.png", "position": "bottom-right", "opacity": 0.6, "size": 0.09 }
}The watermark is drawn last, over everything. size is its width as a fraction of the canvas.
From a URL, in one call#
import { capture, render } from 'screenmat/node'
import { writeFile } from 'node:fs/promises'
const { buffer } = await render({
input: await capture('http://localhost:5173', { waitFor: '#app' }),
settings: { frame: 'browser', url: 'localhost:5173', seed: 1 },
scale: 2,
})
await writeFile('docs/images/home.webp', buffer)capture launches and closes its own browser. When the page needs a session — a login, a cookie, a state set up by clicking — drive Playwright yourself, as below, and hand over the screenshot.
From a browser test, without touching disk#
import { chromium } from 'playwright'
import { render } from 'screenmat/node'
import { writeFile } from 'node:fs/promises'
const browser = await chromium.launch()
const page = await browser.newPage({ viewport: { width: 1440, height: 900 } })
await page.goto('http://localhost:5173')
const { buffer } = await render({
input: await page.screenshot(),
settings: { frame: 'browser', url: 'localhost:5173', seed: 1 },
scale: 2,
})
await writeFile('docs/images/home.webp', buffer)
await browser.close()input accepts raw bytes, so a screenshot that was just produced in memory never has to be written out first.
Regenerate a docs set in CI#
import { render } from 'screenmat/node'
import { readdir, writeFile } from 'node:fs/promises'
for (const file of await readdir('docs/raw')) {
if (!file.endsWith('.png')) continue
const { buffer, format } = await render({ input: `docs/raw/${file}`, style: 'docs', scale: 2 })
await writeFile(`docs/images/${file.replace(/\.png$/, `.${format}`)}`, buffer)
}Pin a seed in the style and the output is byte-stable across runs, so the diff only moves when a screenshot actually changed.
Troubleshooting#
Every layer sits too high. You converted from image pixels without going through inspect(). The screenshot starts below the title bar, or inside the bezel. See Coordinates.
A layer is off by a lot vertically, and the shot is not 4:3. y is divided by the width, never by the height. A 16:9 screenshot only reaches y 0.5625.
My arrow points the wrong way. w and h are signed, and the arrow runs from (x, y) to (x + w, y + h). Do not normalise the rect.
I got a PNG and I asked for WebP. This build of Node has no WebP encoder. The returned format says so, and the file name follows it — better than a .webp that is really a PNG.
A setting I passed had no effect. Check it exists on the façade you used: blur, shapes, shapeOpacity, saturation and contrast have no CLI flag and no MCP parameter. See the capability table.
A value came out different from what I sent. Out-of-range values are clamped, and unknown enum values fall back to their default. The resolved settings are in the render result, and in --json output.
One of my layers vanished. An unknown kind is dropped rather than failing the whole scene. Check the spelling against the seven kinds in Scene format. hidden: true also removes a layer completely — including a redaction, which then hides nothing.
The MCP server refused to write. output must resolve under the write root: the folder of the first screenshot, or SCREENMAT_OUT. Pass a relative path, or widen the root. See Writing safely.
The MCP server wrote to a path I did not ask for. It never overwrites; an existing file makes it try -2, -3, and so on. The path it actually used is in the return value.
A style name is not found. The name is the file name without extension, and the error message lists what is available. Check SCREENMAT_STYLES if the directory is not the default one.