Overview#
screenmat turns a raw screenshot into a shareable visual: a rounded macOS-style window, a generative background derived from the screenshot's own colours, annotations, redaction, multi-shot compositions, high-resolution export.
The web app is one door. This documentation is about the other one — the machine door: the same engine, callable from a build script, a docs generator, or an AI agent in another project.
render(spec) → Buffer
inspect(input) → geometry
cli/api.ts
▲
┌─────────────────────┼─────────────────────┐
│ │ │
cli/main.ts cli/mcp.ts import
command line MCP over stdio from a scriptThe three façades are wrappers with no logic of their own. api.ts holds everything, and api.ts calls renderScene() — the very same function that draws the live preview in the browser. There is one rendering path in this project, so a file produced here is identical to what the app would export.
What you can drive#
- Capture a web page from its URL — your dev server included — in a headless browser on your own machine.
- Frame a screenshot (
browser,macbook,iphone, or no frame at all). - Generate a deterministic background — from the screenshot colours (
mesh,gradient,solid), the real macOS wallpapers from Big Sur to Golden Gate (tahoe-dark,sonoma-light, …), the Windows ones from XP to 11 (windows-11-dark,windows-xp, …), dithered (bayer,halftone,atkinson,contours,truchet, … eleven patterns) — or use an image. - Place annotations: text, badges, arrows, lines, boxes, ellipses.
- Redact a region — blurred, pixelated, or filled, baked into the pixels.
- Compose several shots (
stack,side,tilt3d) in one visual. - Stamp a watermark.
- Recall a style saved from the app by name, so a machine never restates a dozen settings.
Requirements#
- Node 24 or newer. From npm,
pnpm dlx screenmatorpnpm add -D screenmat; the package is compiled JavaScript, also attached to each GitHub release asscreenmat.tgz. From a clone, Node runs the TypeScript incli/directly — there is no build step. - Wallpapers. The macOS and Windows backgrounds are © Apple and © Microsoft and are not in the package; they work from a clone only.
@napi-rs/canvas, which provides Canvas 2D outside the browser. It ships as anoptionalDependency, together with@modelcontextprotocol/sdkandzodfor the MCP server. The web bundle contains none of them.- To capture a URL only:
playwright-core, also optional, and a browser — the installed Google Chrome, orpnpm exec playwright-core install chromium.
pnpm installcli/dom-shim.ts installs document, DOMMatrix and friends on top of @napi-rs/canvas, and src/lib/ runs unchanged. That shim is the only place in the project where a browser global is polyfilled.
Quickstart#
Three ways in, same engine, same output.
# Command line — defaults are already good.
pnpm dlx screenmat screenshot.png # from a clone: pnpm cli screenshot.png
# → screenshot-screenmat.webp 3200×2400 188464 octets// Node script — the direct import.
import { render } from 'screenmat/node'
import { writeFile } from 'node:fs/promises'
const { buffer, width, height } = await render({
input: 'docs/screenshot.png',
settings: { frame: 'macbook', ratio: '16:9' },
scale: 2,
})
await writeFile('docs/hero.png', buffer)# AI agent — register the MCP server once.
claude mcp add screenmat -- pnpm dlx --package=screenmat screenmat-mcp
# From a clone: claude mcp add screenmat -- node /absolute/path/to/screenmat/cli/mcp.tsWhich façade reaches what#
Every façade goes through the same validator, but they do not expose the same surface. When a setting is missing from the one you are using, the scene file (--spec) or the Node API always has it.
| Capability | CLI | MCP | Node API |
|---|---|---|---|
| Frame, ratio, padding, radius, rotation, theme, URL, seed, grain, shadow | yes | yes | yes |
blur, shapes, shapeOpacity, saturation, contrast | --spec only | --spec only | yes |
| Annotation layers | --spec only | yes | yes |
radius, arrowHead, invert, hidden on a layer | --spec only | no | yes |
| Multi-shot composition | --spec only | layout + spread | yes |
| Watermark, frozen palette, background image | --spec only | no | yes |
| Named style | yes | yes | yes |
| Capture a URL | positional URL | screenmat_capture | capture() |
Guarantees#
- Your images never leave the machine. They are decoded, rendered and encoded in the browser (or in your own Node process). The web app loads a cookieless page counter — Cloudflare Web Analytics — and nothing else; the CLI, the Node API and the MCP server make no network call, except to load a URL you explicitly ask them to capture.
- One rendering path. Preview, web export, CLI and MCP all call
renderScene(). The export matches the preview by construction. - External JSON is validated field by field. A scene produced by a model is untrusted input: every value is checked, clamped, or replaced by its default. See Scene format.
- Redaction is baked into the pixels under the window clip, never applied in CSS. Masked data is unreadable in the exported file.
Where to go next#
- CLI — every flag, with its default and its bounds.
- MCP server — the three tools an agent sees, and the write guard.
- Node API —
render()andinspect()signatures. - Scene format — the full JSON, field by field.
- Coordinates — read this before placing a single layer.
- Styles — set it once in the app, recall it by name.
- Recipes — short, runnable examples, and troubleshooting.