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.

text
                    render(spec) → Buffer
                    inspect(input) → geometry
                          cli/api.ts
                              ▲
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   cli/main.ts           cli/mcp.ts            import
   command line          MCP over stdio        from a script

The 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 screenmat or pnpm add -D screenmat; the package is compiled JavaScript, also attached to each GitHub release as screenmat.tgz. From a clone, Node runs the TypeScript in cli/ 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 an optionalDependency, together with @modelcontextprotocol/sdk and zod for 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, or pnpm exec playwright-core install chromium.
bash
pnpm install

cli/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.

bash
# 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
ts
// 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)
bash
# 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.ts

Which 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.

CapabilityCLIMCPNode API
Frame, ratio, padding, radius, rotation, theme, URL, seed, grain, shadowyesyesyes
blur, shapes, shapeOpacity, saturation, contrast--spec only--spec onlyyes
Annotation layers--spec onlyyesyes
radius, arrowHead, invert, hidden on a layer--spec onlynoyes
Multi-shot composition--spec onlylayout + spreadyes
Watermark, frozen palette, background image--spec onlynoyes
Named styleyesyesyes
Capture a URLpositional URLscreenmat_capturecapture()

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() and inspect() 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.