@zumer/snapdom-plugins

@zumer/snapdom-plugins

Official plugins for SnapDOM — extend and transform DOM captures with zero core changes.

Install

npm install @zumer/snapdom-plugins

Usage

Import plugins individually (recommended for tree-shaking):

import { snapdom } from '@zumer/snapdom';
import { filter } from '@zumer/snapdom-plugins/filter';
import { timestampOverlay } from '@zumer/snapdom-plugins/timestamp-overlay';

const result = await snapdom(element, {
  plugins: [filter({ preset: 'grayscale' }), timestampOverlay()]
});
const png = await result.toPng();

Or import everything at once:

import { filter, timestampOverlay, replaceText } from '@zumer/snapdom-plugins';

CDN (no install):

import { snapdom } from 'https://esm.sh/@zumer/snapdom';
import { filter } from 'https://esm.sh/@zumer/snapdom-plugins/filter';

Plugins

filter

Applies CSS filter effects to the captured clone.

import { filter } from '@zumer/snapdom-plugins/filter';

snapdom(el, { plugins: [filter({ preset: 'grayscale' })] });

Option	Type	Default	Description
preset	string	—	'grayscale' | 'sepia' | 'blur' | 'invert' | 'vintage' | 'dramatic'
filter	string	''	Raw CSS filter string, e.g. 'blur(2px) contrast(1.2)'

timestamp-overlay

Adds a translucent timestamp label to the captured clone.

import { timestampOverlay } from '@zumer/snapdom-plugins/timestamp-overlay';

snapdom(el, { plugins: [timestampOverlay({ position: 'top-right', format: 'date' })] });

Option	Type	Default	Description
format	string | function	'datetime'	'datetime' | 'date' | 'time' | 'iso' | custom (Date) => string
position	string	'bottom-right'	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
background	string	'rgba(0,0,0,0.6)'	Label background color
color	string	'#fff'	Label text color
fontSize	number	11	Font size in px

replace-text

Find-and-replace text in the captured clone. Supports strings and regex.

import { replaceText } from '@zumer/snapdom-plugins/replace-text';

snapdom(el, {
  plugins: [replaceText({
    replacements: [
      { find: 'DRAFT', replace: 'APPROVED' },
      { find: /\d{4}-\d{2}-\d{2}/, replace: '[REDACTED]' }
    ]
  })]
});

Option	Type	Default	Description
replacements	Array<{ find: string|RegExp, replace: string }>	[]	List of find/replace pairs

color-tint

Tints the entire capture to a specified color using a mix-blend-mode overlay.

import { colorTint } from '@zumer/snapdom-plugins/color-tint';

snapdom(el, { plugins: [colorTint({ color: 'royalblue', opacity: 0.4 })] });

Option	Type	Default	Description
color	string	'red'	Any CSS color value
opacity	number	1	Overlay opacity (0–1)

ascii-export

Adds a toAscii() export method that converts captures to ASCII art.

import { asciiExport } from '@zumer/snapdom-plugins/ascii-export';

const result = await snapdom(el, { plugins: [asciiExport({ width: 100 })] });
const art = await result.toAscii();
console.log(art);

Option	Type	Default	Description
width	number	80	Character width of output
charset	string	' .:-=+*#%@'	Characters from lightest to darkest
invert	boolean	false	Invert luminance mapping

pdf-image

Exports the capture as a PNG embedded in a downloadable PDF (A4). Adds a toPdfImage() method.

import { pdfImage } from '@zumer/snapdom-plugins/pdf-image';

const result = await snapdom(el, { plugins: [pdfImage({ orientation: 'landscape' })] });
await result.toPdfImage(); // triggers download

Option	Type	Default	Description
orientation	string	'portrait'	'portrait' | 'landscape'
quality	number	0.92	JPEG quality (0–1)
filename	string	'capture.pdf'	Download filename

html-in-canvas

Uses the experimental WICG drawElementImage API for direct DOM-to-canvas rendering where supported. Falls back gracefully.

import { htmlInCanvas } from '@zumer/snapdom-plugins/html-in-canvas';

snapdom(el, { plugins: [htmlInCanvas()] });

This plugin uses an experimental browser API and may not work in all environments.

agent-map

Produces a Set-of-Mark package for visual agents: an annotated screenshot with numbered badges on interactive elements, plus a compact JSON map from badge index → role / accessible name / bbox / state. One call, fully client-side.

import { agentMap } from '@zumer/snapdom-plugins/agent-map';

const result = await snapdom(el, { plugins: [agentMap()] });
const { image, map, dimensions } = await result.toAgentMap();

// image: data URL of the screenshot with numbered red badges overlaid
// map:   [{ i, n, r, b, s? }, …] — index, name, role, bbox, state
// Agent says "click element 2" → map[2].b gives [x, y, w, h]

Map entry shape (default fields: 'minimal'):

Key	Type	Description
i	number	Index matching the badge drawn on the image
n	string	Accessible name (aria-label → labelledby → alt → title → labels → textContent, truncated to 60 chars)
r	string	ARIA-style role (button, link, checkbox, radio, textbox, combobox, slider, heading, …) — derived from role attribute or implicit role of the element
b	[x, y, w, h]	Bounding box in pixels, scaled against maxImageWidth
s	object?	State: included only when at least one key is meaningful — checked, disabled, focus, expanded, pressed, selected, value, open, selectedText, covered

Example map for a checkout form:

[
  { i: 0, n: 'Email',         r: 'textbox',  b: [28,  80, 280, 34], s: { value: '[e-mail]' } },
  { i: 1, n: 'Send product updates', r: 'checkbox', b: [28, 134,  13, 13], s: { checked: true } },
  { i: 2, n: 'Apply coupon',  r: 'button',   b: [28, 176, 114, 38], s: { expanded: false } },
  { i: 3, n: 'Remove coupon', r: 'button',   b: [150, 176, 140, 38], s: { disabled: true } },
  { i: 4, n: 'Pay $53.90',    r: 'button',   b: [28, 220,  97, 38] }
]

Options

Option	Type	Default	Description
image	'annotated' | 'raw' | false	'annotated'	'annotated' overlays numbered badges; 'raw' skips badges; false skips image generation entirely (no canvas draw, no toDataURL — cheapest path).
fields	'minimal' | 'full'	'minimal'	'full' adds t (raw text content) and a (meaningful attributes) per entry.
semantic	boolean	false	Include non-interactive structural elements (headings, paragraphs, landmarks). Off by default — agents act on interactive.
maxImageWidth	number	1024	Downscale target for the image; bboxes rescale to match.
imageFormat	'png' | 'jpg' | 'webp'	'png'	Image format (only used when image is rendered).
imageQuality	number	0.8	Quality for lossy formats.
interactiveSelector	string	see below	CSS selector for interactive elements.
semanticSelector	string	see below	CSS selector for semantic elements (used when semantic: true).
labelStyle	object	{}	Override badge styles.

Defaults:

• interactive: a[href], button, input, select, textarea, [role="button"|"link"|"tab"|"menuitem"|"checkbox"|"radio"|"switch"|"slider"|"combobox"|"textbox"], [tabindex]:not([tabindex="-1"]), summary, [contenteditable="true"]
• semantic: h1–h6, nav, main, article, section, header, footer, figcaption, blockquote, legend, p

Per-call options override constructor options (e.g. result.toAgentMap({ image: false })).

When to use

• Visual agents using Set-of-Mark prompting — one call gives you both the labelled image and the coordinate lookup table.
• Computer-use / browser-agent harnesses that need click coordinates for a vision model's output.
• Visual QA with an LLM judge — compare before/after captures with structured element identity.
• Dataset generation for vision-LLM fine-tuning — (image, map) pairs.

Because it runs entirely in the browser, it works in contexts where Playwright / Puppeteer can't: Chrome extensions, SaaS web apps capturing the user's own page, Electron apps capturing their own window.

html-export

Adds a toHtml() export that returns the capture as a self-contained, re-renderable HTML document (clone + inlined styles/fonts) instead of pixels. It unwraps the SVG <foreignObject> SnapDOM already produced, so the markup and CSS match the capture byte-for-byte — nothing is rasterized.

import { htmlExport } from '@zumer/snapdom-plugins/html-export';

const result = await snapdom(el, { plugins: [htmlExport()] });
const html = await result.toHtml();              // full <!DOCTYPE html> string

// Or download a .html file:
await result.toHtml({ download: 'snapshot.html' });

Option	Type	Default	Description
fullDocument	boolean	true	Wrap output in <!DOCTYPE html>…; if false, return just <style> + the fragment
filename	string	'capture.html'	Download filename when opts.download is true

Per-call opts: download (boolean \| string — true triggers download, a string sets the filename), plus fullDocument / filename overrides. Returns the HTML string.

gif-export

Adds a toGif() export that records an animated GIF by re-capturing the live element over time and encoding the frames. The GIF89a encoder (median-cut quantization + LZW) is built in — no dependencies. Returns a Blob (image/gif).

import { gifExport } from '@zumer/snapdom-plugins/gif-export';

const result = await snapdom(el, { plugins: [gifExport({ fps: 12, duration: 3000 })] });
const blob = await result.toGif();

// Or download directly:
await result.toGif({ download: 'animation.gif' });

Option	Type	Default	Description
fps	number	10	Frames per second
duration	number	2000	Total duration in ms (ignored if frames is set)
frames	number	—	Explicit frame count (overrides duration)
maxColors	number	256	Palette size per frame (2–256)
background	string	'#ffffff'	Color composited under transparent pixels
scale	number	1	Capture scale
repeat	number	0	Loop count (0 = forever, -1 = play once)
filename	string	'capture.gif'	Download filename

Per-call opts override any constructor option, plus download (boolean \| string). Each frame is captured live, so CSS animations / dynamic content are recorded as they play.

video-export

Adds a toMp4() export that records a video by re-capturing the live element over time and encoding the frames with the native MediaRecorder. Returns a Blob whose type reflects what was actually produced.

import { videoExport } from '@zumer/snapdom-plugins/video-export';

const result = await snapdom(el, { plugins: [videoExport({ fps: 30, duration: 4000 })] });
const blob = await result.toMp4();

// Or download directly:
await result.toMp4({ download: true });

Codec reality: MediaRecorder output depends on the browser. Safari produces MP4 (H.264); Chromium typically produces WebM (VP8/VP9). When MP4 isn't supported the plugin falls back to WebM, warns in the console, and the downloaded file extension is set to .mp4 / .webm accordingly.

Option	Type	Default	Description
fps	number	10	Frames per second
duration	number	2000	Total duration in ms (ignored if frames is set)
frames	number	—	Explicit frame count (overrides duration)
background	string	'#ffffff'	Color composited under transparent pixels
scale	number	1	Capture scale
bitrate	number	—	videoBitsPerSecond passed to MediaRecorder
filename	string	—	Download filename (extension auto-set to .mp4 / .webm)

Requires MediaRecorder (unavailable in some headless environments). Per-call opts override any constructor option, plus download (boolean \| string).

Plugin registration

Global (applies to all captures):

import { snapdom } from '@zumer/snapdom';
import { filter } from '@zumer/snapdom-plugins/filter';

snapdom.plugins(filter({ preset: 'sepia' }));

Per-capture (overrides global for that call):

const result = await snapdom(element, {
  plugins: [filter({ preset: 'dramatic' })]
});

Per-capture plugins run before global ones. Duplicate plugin names are skipped automatically.

Build your own plugin

Use the template to scaffold a new plugin in seconds:

npx degit zumerlab/snapdom/packages/plugin-template my-plugin

See PLUGIN_SPEC.md for the full hook specification and CONTRIBUTING_PLUGINS.md to get your plugin listed on the community page.

License

MIT