Getting started

Annot publishes a family of packages on npm. Pick the entry point that matches how you want to use it.

Package	Use it when	npm
@ingcreators/annot-playwright	You run Playwright tests and want to attach annotated screenshots to the HTML report.
@ingcreators/annot-mcp	You drive Annot from an AI agent (Claude Desktop / Claude Code / Cursor) via the Model Context Protocol.
annot-product-docs (trio)	You want a docs site + Excel screen-specifications spreadsheet generated from the same MDX, kept in sync with Playwright snapshots.
@ingcreators/annot-annotator	You want the headless annotator from any Node script — CI, a CLI, a build pipeline.
@ingcreators/annot-core	You’re building a new host (extension, editor, plugin) and need the SVG annotation format + storage types.

If in doubt, start with annot-playwright — it’s the highest- leverage entry point and pulls the rest in transitively. If you’re wiring an AI agent, start with annot-mcp. If you’re shipping product docs alongside a UI, the living-product-docs trio is the dedicated path.

What you get

The same annotation DSL — rect / circle / arrow / text / callout / raw with an intent shorthand mapped to design-system colours — works from any of the packages:

import {
  test,
  type BboxAnnotation,
} from "@ingcreators/annot-playwright";

test("login form is reachable", async ({ page, annotator }) => {
  await page.goto("https://example.com/login");
  const submit = page.getByRole("button", { name: "Sign in" });
  const box = (await submit.boundingBox())!;

  await annotator.annotateScreenshot(page, {
    annotations: [
      { type: "rect", bbox: box, intent: "error" },
      { type: "callout", at: { x: 50, y: 50 }, targetBbox: box,
        content: "Failing here" },
    ] satisfies BboxAnnotation[],
  });
});

The resulting PNG attaches to the Playwright HTML report next to the failing step. AI agents emit the same BboxAnnotation[] shape over MCP tool calls; see AI agents.

Need smaller files? Pass encode: { format: "smart", saveSizePreset: "standard" } and the output PNG-32 gets auto-quantized to PNG-8 (UI-heavy) or compressed to JPEG (photo-heavy). See Encode pipeline.

Requirements

• Node 20+ for annot-annotator (it uses native ESM and @resvg/resvg-js prebuilds).
• Playwright 1.50+ as a peer dep of annot-playwright.
• No browser at runtime — the annotator runs entirely in Node.