DOMShot Agent Package

@usedomshot/cli gives AI agents and automation tools local screenshot tools for webpage UI. It can inspect a page, find useful DOM elements, capture one element, capture several related elements, create contact sheets, and build polished PNG shot packs.

DOMShot is the eyes and camera. The calling agent is the brain. DOMShot returns evidence such as selectors, dimensions, confidence, warnings, decisions, contact sheets, reports, and image paths. The agent decides which visuals support the story it is writing.

Start with AGENT_GUIDE.md when an agent needs to choose the right workflow, retry a weak capture, or work with logged-in pages.

License and Source

The @usedomshot/cli package is published under the ISC license. That license applies to this installable CLI/Node/MCP package only.

The DOMShot Chrome extension, hosted app, brand, private source repository, and product assets remain proprietary unless stated otherwise. The public GitHub repository at https://github.com/rubnx/domshot is for package docs, examples, issues, support notes, and public product information.

Install

npm install @usedomshot/cli
npx playwright install chromium

Node 20 or newer is required. npx playwright install chromium installs the local browser DOMShot uses for default captures.

Update an existing project with:

npm update @usedomshot/cli

For global CLI/MCP installs, use:

npm install -g @usedomshot/cli@latest

The package ships three agent-facing surfaces:

• Node API: import functions from @usedomshot/cli.
• CLI: run domshot ... commands and read JSON output.
• MCP server: run domshot mcp so MCP-compatible hosts can call DOMShot tools.

Quick Decision

| Need | Use | | --- | --- | | Capture one exact known element | captureDomshot({ selector }) or domshot capture <url> <selector> | | Capture one element by plain language | captureDomshot({ target }) or domshot capture <url> --target "pricing card" | | Let DOMShot check nearby crops and style automatically | captureDomshot({ target, style: "auto" }) or domshot capture <url> --target "pricing card" --style auto | | See what the page can offer | inspectDomshotPage or domshot inspect | | Get suggested use and styling | recommendDomshotShots or domshot recommend | | Decide before writing PNGs | createDomshotPlan or domshot plan | | Compare candidates visually | createDomshotContactSheet or domshot contact-sheet | | Capture several similar elements | captureDomshotSet or domshot capture-set | | Build a screenshot pack for a section or post | createDomshotShotPack or domshot shot-pack | | Use a logged-in browser tab | CDP current-page commands or browser: { mode: "cdp" } |

If both selector and target are provided, selector wins.

Node API

Capture One Selector

Use selector mode when the caller knows the exact CSS selector and wants precise control.

import { captureDomshot } from "@usedomshot/cli";

const result = await captureDomshot({
  url: "https://example.com",
  selector: "h1",
  output: "artifacts/domshot/heading.png",
  preset: "floating"
});

console.log(result.path, result.width, result.height, result.fallback);

Expected output: one PNG file and metadata with path, width, height, selector, fallback, and optional warning.

Capture One Target

Use target mode when the agent knows what it wants but not the selector.

import { captureDomshot } from "@usedomshot/cli";

const result = await captureDomshot({
  url: "https://example.com",
  target: "pricing card",
  output: "artifacts/domshot/pricing-card.png",
  style: "auto"
});

console.log(result.selector, result.target?.score, result.verification?.reason, result.style?.reason, result.path);

DOMShot scans visible elements, scores likely matches using DOM and visual signals, resolves the target to a selector, verifies nearby crop alternatives, then uses the same capture pipeline. Target mode uses nearby verification by default.

Smart Verification and Auto Style

Use style: "auto" when the agent wants DOMShot to choose a practical presentation instead of hard-coding background, shadow, and crop settings.

const result = await captureDomshot({
  url: "https://example.com",
  target: "feature card",
  output: "artifacts/domshot/feature-card.png",
  style: "auto"
});

For exact selectors, DOMShot stays exact by default. Add verify: true when the selector may point at inner text and the parent card could be the better visual crop.

const result = await captureDomshot({
  url: "https://example.com",
  selector: ".pricing-card-title",
  verify: true,
  style: "auto",
  output: "artifacts/domshot/pricing-card.png"
});

Smart verification considers the selected element, useful parents, children, and siblings. It avoids giant shells and returns sanitized verification metadata with the selected selector, alternatives, confidence, and reason. Auto style returns style metadata with the chosen background/shadow/padding/aspect settings and the variants it considered. DOMShot does not include raw page text in this metadata.

Use an Existing Playwright Page

Use captureElement when a script already controls a Playwright page and has prepared the page state.

import { chromium } from "playwright";
import { captureElement } from "@usedomshot/cli";

const browser = await chromium.launch();
const page = await browser.newPage();

try {
  await page.goto("https://example.com");
  const result = await captureElement(page, {
    selector: "h1",
    output: "artifacts/domshot/existing-page-heading.png",
    background: "transparent"
  });

  console.log(result.path);
} finally {
  await browser.close();
}

Plan Before Capture

Use a plan when the agent should decide what is worth capturing before writing final PNG files.

import { createDomshotPlan } from "@usedomshot/cli";

const plan = await createDomshotPlan({
  url: "https://example.com",
  intent: "homepage feature section",
  target: "feature cards",
  count: 4,
  output: "artifacts/domshot/homepage-plan.json",
  style: "auto"
});

console.log(plan.shots.map((shot) => ({
  selector: shot.selector,
  suggestedOutput: shot.suggestedOutput,
  decision: shot.decision.decision,
  why: shot.decision.why,
  retryAdvice: shot.decision.retryAdvice
})));

Expected output: a JSON plan with selectors, suggested outputs, style suggestions, decisions, risks, and retry advice. A plan does not include image payloads.

Create a Shot Pack

Use a shot pack when the agent needs final assets for a homepage section, feature section, pricing page, blog post, docs page, or social post.

import { createDomshotShotPack } from "@usedomshot/cli";

const pack = await createDomshotShotPack({
  url: "https://example.com",
  intent: "homepage feature section",
  target: "feature cards",
  count: 4,
  outputDir: "artifacts/domshot/homepage-shot-pack",
  style: "auto"
});

console.log(pack.contactSheet, pack.report);
console.log(pack.items.map((item) => ({
  path: item.path,
  use: item.use,
  confidence: item.confidence,
  decision: item.decision.decision,
  selectedReason: item.selectedReason,
  styleReason: item.styleReason
})));

Expected output: polished PNG files, a contact sheet, and a sanitized report.json.

Capture a Saved Plan

Use from-plan capture after a plan has been reviewed.

import { captureDomshotPlan } from "@usedomshot/cli";

const result = await captureDomshotPlan({
  fromPlan: "artifacts/domshot/homepage-plan.json",
  url: "https://example.com",
  outputDir: "artifacts/domshot/homepage-captures",
  style: "auto"
});

console.log(result.items.map((item) => ({
  path: item.path,
  selector: item.selector,
  decision: item.decision.decision
})));

The saved plan's selectors and suggested styles are used by default.

CLI

The CLI prints JSON metadata to stdout and writes readable JSON errors to stderr.

domshot capture https://example.com "h1" --out artifacts/domshot/heading.png

domshot capture https://example.com \
  --target "pricing card" \
  --out artifacts/domshot/pricing-card.png \
  --background transparent \
  --shadow soft \
  --aspect-ratio 1:1 \
  --output-width 1200

domshot inspect https://example.com \
  --intent "homepage feature visuals" \
  --target "feature cards" \
  --limit 8

domshot plan https://example.com \
  --intent "homepage feature section" \
  --target "feature cards" \
  --count 4 \
  --out artifacts/domshot/homepage-plan.json \
  --style auto

domshot shot-pack https://example.com \
  --intent "homepage feature section" \
  --target "feature cards" \
  --count 4 \
  --out-dir artifacts/domshot/homepage-shot-pack \
  --style auto

For logged-in or manually prepared pages, attach to an existing Chrome session through CDP:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/automation-chrome-profile"

domshot capture-current --target "dashboard card" \
  --browser cdp \
  --cdp http://127.0.0.1:9222 \
  --out artifacts/domshot/dashboard-card.png

domshot shot-pack-current \
  --intent "dashboard feature visuals" \
  --target "dashboard cards" \
  --browser cdp \
  --cdp http://127.0.0.1:9222 \
  --out-dir artifacts/domshot/dashboard-pack \
  --style auto

Use a dedicated automation profile. Do not point DOMShot at a person's regular Chrome profile.

MCP

Run the stdio server:

domshot mcp

Example MCP client config:

{
  "mcpServers": {
    "domshot": {
      "command": "domshot",
      "args": ["mcp"]
    }
  }
}

Keep this config stable across DOMShot releases. To update the MCP server, update the installed npm package instead of changing the MCP args:

npm install -g @usedomshot/cli@latest

Only pin a version in MCP config when reproducibility matters more than automatic updates.

Tools:

capture_domshot
inspect_domshot_page
recommend_domshot_shots
create_domshot_plan
capture_domshot_plan
create_domshot_contact_sheet
capture_domshot_set
create_domshot_shot_pack

Use inspect_domshot_page when the agent is unsure what exists. Use create_domshot_plan when the agent should decide before writing files. Use create_domshot_shot_pack when the agent needs final image assets for a section, post, docs page, pricing page, or social post.

Example shot pack input:

{
  "url": "https://example.com",
  "intent": "homepage feature section",
  "target": "feature cards",
  "count": 4,
  "outputDir": "artifacts/domshot/homepage-shot-pack",
  "style": "auto"
}

MCP v1 returns JSON text with paths, dimensions, selectors, warnings, decisions, confidence, contact sheet paths, report paths, and fallback status. It writes PNG files to disk and does not return base64 image payloads.

Browser Modes

| Mode | Use when | Example | | --- | --- | --- | | launch | Public pages that do not need existing session state | browser: { mode: "launch", headless: true } | | cdp | The page is already open, logged in, or manually prepared | browser: { mode: "cdp", endpointURL: "http://127.0.0.1:9222" } | | profile | DOMShot should launch Chrome with a dedicated automation profile | browser: { mode: "profile", userDataDir: "automation-chrome-profile" } |

CDP in plain language: Chrome exposes a local debugging port, and DOMShot connects to that browser instead of starting a fresh one.

Common Options

• selector: exact CSS selector to capture.
• target: plain-language target such as pricing card, modal, hero section, or download button.
• targetMatch: best or strict; use strict when ambiguity should fail.
• intent: purpose for inspection, recommendations, plans, and shot packs.
• kinds: restrict candidates to kinds such as card, pricing, feature, hero, dashboard, table, form, button, modal, or section.
• limit or count: how many candidates or final shots to consider.
• style: "auto": choose practical styling from the detected element kind.
• verify: check nearby parent/current/child/sibling crops before final capture.
• candidateDepth: none or nearby; target mode defaults to nearby verification.
• styleVariants: none or auto; enabled automatically when style: "auto" is used for one-shot captures.
• background, shadow, padding, cornerRadius, aspectRatio, outputWidth: styling controls for final PNGs.
• steps: click, wait, scroll, or delay before inspecting or capturing.
• fallback: screenshot accepts visible-pixel fallback; throw fails instead.

Result Metadata

Important fields:

• path: where the PNG or report was written.
• selector: selector actually captured.
• target: sanitized target-resolution metadata when target mode was used.
• verification: sanitized crop verification metadata when smart verification ran.
• style: sanitized auto-style metadata when style: "auto" ran.
• confidence and visualScore: evidence for whether a candidate is likely useful.
• warnings: review prompts such as lower confidence, clipping, iframe limits, or fallback.
• decision: deterministic use, review, retry, or skip guidance.
• selectedReason and styleReason: why an item was captured and styled that way.
• rejectedCandidates: sanitized reasons other candidates were skipped.
• fallback: whether DOMShot used a visible screenshot fallback instead of DOM rendering.

Privacy

Treat local screenshot work as sensitive when pages are private or logged in:

• Do not commit generated screenshots, reports, browser profiles, auth state, private URLs, or private selectors.
• Use a dedicated automation profile for CDP/profile workflows.
• Do not paste private page text or full private command output into public issues, docs, commits, or pull requests.
• DOMShot metadata is sanitized, but selectors and local paths can still reveal context.
• Plans and reports intentionally omit raw page text, auth state, and screenshot payloads.

Troubleshooting

| Symptom | First fix | | --- | --- | | Playwright says Chromium is missing | Run npx playwright install chromium. | | Selector not found | Confirm the selector, wait for page state, or increase timeoutMs. | | Selector not unique | Use a more specific selector or intentional match: "first". | | Target not found | Use a clearer target, add steps, or switch to selector mode. | | Wrong visual selected | Use target mode or verify: true, run inspect, create a contact sheet, narrow target, add kinds, or use selector mode. | | Crop has no background or looks weak | Use style: "auto" so DOMShot can try transparent, paper, and graphite treatments. | | Lazy content missing | Add scroll, wait, or waitFor steps. | | Logged-in page opens logged out | Use CDP attach or profile mode with a dedicated automation profile. | | Fallback screenshot used | Accept it if visible pixels are enough, or use fallback: "throw". |

For detailed retry guidance, use AGENT_GUIDE.md.

Examples

Packaged examples live in examples/:

• target-capture.mjs: one target capture.
• capture-pricing-cards.mjs: pricing card set.
• homepage-feature-shot-pack.mjs: homepage feature section shot pack.
• blog-docs-illustration.mjs: inspect and recommend visuals for docs or blog content.
• logged-in-dashboard-cdp.mjs: CDP current-page shot pack for a logged-in dashboard.
• mcp-config.json: minimal MCP config.

Validate Before Publish

@usedomshot/cli is configured for public npm publishing under the usedomshot organization.

Useful validation commands:

npm run check:agent
npm run test:agent
npm run build:agent
npm run smoke:agent:cli
npm run smoke:agent:cdp
npm run smoke:agent:mcp
npm --workspace @usedomshot/cli pack --dry-run

Publish from packages/agent with:

npm publish --access public

The package tarball should include dist, README.md, AGENT_GUIDE.md, examples, the domshot CLI bin, and .d.ts files. It should not include local output folders, browser profiles, screenshots, reports, or test fixtures.