@ingcreators/annot-mcp 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,193 @@
 # @ingcreators/annot-mcp
 
+## 0.3.2
+
+### Patch Changes
+
+- 0c7ac26: **Relocate `burnRedactions` from `@ingcreators/annot-mcp` to
+  `@ingcreators/annot-annotator`** — Phase 3e of
+  `docs/plans/living-spec-authoring-roadmap.md` (Phase 3 follow-up).
+
+  The destructive raster burn primitive (solid / mosaic / blur over
+  a PNG buffer, built on `@napi-rs/canvas`) historically lived in
+  `@ingcreators/annot-mcp` because the MCP server's
+  `annot_redact_screenshot` tool was the first caller. The function
+  itself has no MCP-specific surface — it's pure
+  (`pngBytes + regions → pngBytes`). To let non-MCP callers consume
+  it without dragging the MCP server's dep footprint (Playwright,
+  `@modelcontextprotocol/sdk`, etc.), the primitive moves to
+  `@ingcreators/annot-annotator` — the canonical Node-side raster
+  home, which already depends on `@napi-rs/canvas` for its encode
+  pipeline (so the move adds **zero** transitive deps).
+
+  ### `@ingcreators/annot-annotator` — new public surface
+
+  ```ts
+  import {
+    burnRedactions,
+    type RedactRegion,
+  } from "@ingcreators/annot-annotator";
+
+  const out = await burnRedactions(pngBytes, [
+    {
+      bbox: { x: 10, y: 20, width: 100, height: 30 },
+      style: "solid",
+      color: "#000000",
+    },
+    { bbox: { x: 200, y: 100, width: 80, height: 40 }, style: "mosaic" },
+    { bbox: { x: 0, y: 0, width: 64, height: 64 }, style: "blur" },
+  ]);
+  ```
+
+  `RedactRegion` is exposed as an alias of `BboxRedactRegion`
+  (structurally identical, already declared in the DSL types) so
+  existing MCP-side consumers see no shape change.
+
+  ### `@ingcreators/annot-mcp` — no public API change
+
+  The existing `burnRedactions` + `RedactRegion` re-exports from
+  the package root keep working byte-identical, sourced from the
+  annotator instead of the old MCP-local file. MCP's
+  `annot_redact_screenshot` / `annot_redact_url` tools continue
+  to import from `../redact/burn.js`, which is now a one-line
+  re-export from annotator.
+
+  ### Compatibility
+
+  Additive on annotator's side; zero behaviour change on MCP's
+  side. Tests move with the code (annotator 64 → 71 passed; MCP
+  91 → 84 passed — same scenarios at the new home).
+
+  ### Out of scope
+
+  `@napi-rs/canvas` stays as an MCP direct dep — `compare/diff.ts`
+  and several other MCP tool tests still use it directly, so
+  collapsing it onto a transitive-via-annotator import is a
+  separate cleanup.
+
+- 64dc6e8: **Relocate `diffScreenshots` from `@ingcreators/annot-mcp` to
+  `@ingcreators/annot-annotator`** — Phase 3i of
+  `docs/plans/living-spec-authoring-roadmap.md` (Phase 3
+  follow-up #2). Same pattern as 3e's `burnRedactions` relocate.
+
+  The pixelmatch-driven PNG comparison + contiguous-region bbox
+  aggregation lived in `@ingcreators/annot-mcp/compare/` for
+  historical reasons (the MCP server's
+  `annot_compare_screenshots` tool was the first caller). The
+  function itself has no MCP-specific surface — it's pure
+  (`pngBytes + pngBytes → DiffResult`). Relocating it to
+  `@ingcreators/annot-annotator` lets non-MCP callers
+  (Playwright visual regression fixtures, Astro pixel drift CI,
+  custom test reporters, editor before/after preview) consume
+  it without dragging the MCP server's dep footprint.
+
+  ### `@ingcreators/annot-annotator` — new public surface
+
+  ```ts
+  import {
+    diffScreenshots,
+    aggregateDiffRegions,
+    DimensionMismatchError,
+    type DiffResult,
+    type DiffOptions,
+  } from "@ingcreators/annot-annotator";
+
+  const result = await diffScreenshots(beforePng, afterPng, { threshold: 0.1 });
+  // → { mismatchedPixels: number, regions: BBox[], width, height }
+  ```
+
+  annotator gains `pixelmatch` (~4 KB, no transitive deps) as a
+  runtime dep.
+
+  ### `@ingcreators/annot-mcp` — no public API change
+
+  The existing `compare/diff.ts` + `compare/aggregate.ts` modules
+  become one-line re-export shims forwarding from annotator. MCP's
+  internal callers (`tools/compare-screenshots.ts`) and any
+  external consumer importing from `@ingcreators/annot-mcp` keep
+  working byte-identical.
+
+  ### Compatibility
+
+  Additive on annotator's side; zero behaviour change on MCP's
+  side. Tests move with the code (annotator 71 → 81 passed; MCP
+  84 → 78 passed — same scenarios at the new home, plus a new
+  `diffScreenshots` smoke test that the MCP-side aggregate-only
+  test didn't cover).
+
+  ### Out of scope
+
+  `pixelmatch` stays as a direct MCP dep — even though MCP no
+  longer imports it from the moved code, it's a tiny package
+  and removing the explicit dep would force consumers to rely
+  on a transitive resolution through annotator, which is more
+  fragile than declaring the intent directly.
+
+- 9697f27: **Export `burnRegions` as an operation-aligned alias for
+  `burnRedactions`** — Phase 3k of
+  `docs/plans/living-spec-authoring-roadmap.md`
+  (Phase 3 follow-up #2). Closes the follow-up.
+
+  `burnRedactions` is named for its first caller's intent (MCP's
+  `annot_redact_screenshot`), but the underlying primitive is a
+  `pngBytes + region[] → pngBytes` raster transform — generic
+  over the caller's purpose. The new export surfaces the
+  operation-aligned name alongside the intent-named original.
+
+  ### `@ingcreators/annot-annotator` — new public export
+
+  ```ts
+  import { burnRegions } from "@ingcreators/annot-annotator";
+
+  // Identical signature + behaviour to burnRedactions.
+  const out = await burnRegions(pngBytes, [
+    { bbox: { x: 10, y: 20, width: 100, height: 30 }, style: "mosaic" },
+  ]);
+  ```
+
+  Identity-equal to `burnRedactions` (`burnRegions === burnRedactions`
+  at the export level) — picking one name over the other is purely
+  a docs-readability choice.
+
+  ### Use cases that motivated the alias
+
+  The function isn't redact-specific — the JSDoc on `burnRedactions`
+  now enumerates:
+  - Editor-side "highlight this region with a translucent colour
+    and ship it baked" workflow.
+  - Visual-regression pre-processing — burn dynamic content
+    (timestamps, login state badges) into the screenshot so pixel
+    diffs stay deterministic.
+  - Watermark / overlay burn for downstream distribution.
+  - Privacy hardening at non-redact regions (e.g. blur a logo in
+    a publicly-shared screenshot).
+
+  For any of these, `burnRegions` reads as the natural name.
+  Redact callers stay on `burnRedactions` (still the recommended
+  name when the intent IS redaction); no migration forced.
+
+  ### `@ingcreators/annot-mcp` — no public API change
+
+  MCP's `compare/burn.ts` re-export shim + `index.ts` forward both
+  names. Existing `burnRedactions` callers see no change.
+
+  ### Compatibility
+
+  Additive. `burnRedactions` keeps its public API + JSDoc; the
+  alias is purely additive.
+
+- Updated dependencies [6124d59]
+- Updated dependencies [b5d52f6]
+- Updated dependencies [fa712fd]
+- Updated dependencies [0c7ac26]
+- Updated dependencies [f09a6b1]
+- Updated dependencies [0d19345]
+- Updated dependencies [64dc6e8]
+- Updated dependencies [691bec5]
+- Updated dependencies [9697f27]
+  - @ingcreators/annot-annotator@0.6.0
+  - @ingcreators/annot-product-docs@0.4.0
+
 ## 0.3.1
 
 ### Patch Changes

package/dist/compare/aggregate.d.ts

@@ -1,6 +1 @@
-import { BBox } from '../dsl/types.js';
-/**
- * Walk a pixelmatch diff mask and return one bbox per contiguous
- * changed region. 4-connected adjacency.
- */
-export declare function aggregateDiffRegions(diffRgba: Uint8Array, width: number, height: number): BBox[];
+export { aggregateDiffRegions } from '@ingcreators/annot-annotator';

package/dist/compare/diff.d.ts

@@ -1,30 +1 @@
-import { BBox } from '../dsl/types.js';
-export interface DiffResult {
-    /** Number of mismatched pixels. */
-    mismatchedPixels: number;
-    /** Bounding boxes of contiguous changed regions. */
-    regions: BBox[];
-    /** Dimensions of the input pair. */
-    width: number;
-    height: number;
-}
-export interface DiffOptions {
-    /** Matching threshold (0 to 1); smaller is more sensitive. */
-    threshold?: number;
-}
-export declare class DimensionMismatchError extends Error {
-    constructor(a: {
-        width: number;
-        height: number;
-    }, b: {
-        width: number;
-        height: number;
-    });
-}
-/**
- * Compare two PNGs pixel-by-pixel and return the changed-region
- * bboxes. Throws `DimensionMismatchError` when the inputs have
- * different sizes — the agent has to capture both with the same
- * viewport for the comparison to make sense.
- */
-export declare function diffScreenshots(before: Uint8Array, after: Uint8Array, options?: DiffOptions): Promise<DiffResult>;
+export { type DiffOptions, type DiffResult, DimensionMismatchError, diffScreenshots, } from '@ingcreators/annot-annotator';

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { BBOX_ANNOTATION_SCHEMA, BBOX_REDACT_REGION_SCHEMA, LOCATOR_ANNOTATION_S
 export type { AnnotationStyle, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Locator, LocatorAnnotation, LocatorArrowAnnotation, LocatorCalloutAnnotation, LocatorCircleAnnotation, LocatorRectAnnotation, LocatorRedactRegion, LocatorTextAnnotation, Point, RawAnnotation, RedactStyle, } from './dsl/types.js';
 export { InvalidPngError, type PngDimensions, readPngDimensions, } from './io/png-dimensions.js';
 export { InvalidImageInputError, type ResolvedImage, resolveImageInput, } from './io/read-image.js';
-export { burnRedactions, type RedactRegion } from './redact/burn.js';
+export { burnRedactions, burnRegions, type RedactRegion } from './redact/burn.js';
 export { type CreateServerOptions, createServer } from './server.js';
 export { ANNOTATE_SCREENSHOT_TOOL_NAME, type AnnotateToolResult, annotateScreenshotTool, handleAnnotateScreenshot, } from './tools/annotate-screenshot.js';
 export { ANNOTATE_URL_TOOL_NAME, annotateUrlTool, handleAnnotateUrl, } from './tools/annotate-url.js';