@ingcreators/annot-annotator 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,310 @@
 # @ingcreators/annot-annotator
 
+## 0.7.0
+
+### Minor Changes
+
+- `toEditablePng`'s `EditableInput` gains the schema-2.0 provenance
+  fields (`sourceUrl` / `createdAt` / `producer` / `dpr`), written
+  into the XMP packet as first-class elements. `producer` defaults
+  to `"annotator"`. Prefer these over the old `WELL_KNOWN_TAG_KEYS`
+  smuggling convention (`source` / `capturedAt` tags).
+
+## 0.6.0
+
+### Minor Changes
+
+- 6124d59: **`BboxAnnotation` palette extensions: `freehand` + `focusMask`** —
+  Phase 3b of `docs/plans/living-spec-authoring-roadmap.md`.
+
+  Two new variants on the `BboxAnnotation` union expose the rest of
+  the Annot visual palette to `bboxAnnotationsToSvg()` and through
+  it to `Annotator.toPng()` / `.toSvg()` / `.toEditablePng()`:
+
+  ```ts
+  // Free-form path stroke — `path` is the SVG <path> `d` attribute.
+  {
+    type: "freehand",
+    path: "M100,200 L150,250 L200,210",
+    intent: "info",        // optional — defaults to "error"
+    strokeWidth: 4,        // optional — defaults to 2
+    fill: "#ffeecc",       // optional — defaults to "none"
+  }
+
+  // Dim everything except the cutout region. One <path> with
+  // fill-rule="evenodd" combines a full-image rect with the
+  // cutout — the even-odd rule cancels overlap.
+  {
+    type: "focusMask",
+    cutout: { x: 200, y: 100, width: 80, height: 40 },
+    imageWidth: 1280,
+    imageHeight: 800,
+    dimColor: "rgba(0,0,0,0.5)",   // optional — default same value
+  }
+  ```
+
+  `@ingcreators/annot-product-docs`'s `<Screen annotations>`
+  Image Service composition (Phase 3c) will map yaml
+  `AnnotationSpec` entries to these two primitives plus the
+  existing `rect` / `circle` / `arrow` / `text` / `callout` /
+  `numberedBadge` shapes. Useful standalone for any annotator
+  caller (Playwright fixtures, MCP server, custom test reporters)
+  without involving yaml or MDX.
+
+  **JSON schemas** — `BBOX_ANNOTATION_SCHEMA.oneOf` gains
+  `BBOX_FREEHAND` + `BBOX_FOCUS_MASK` entries so MCP callers can
+  validate either kind at the boundary.
+
+  **Out of scope** — redact (mosaic / blur) needs raster pixel
+  access and is not implementable as an SVG fragment; it stays
+  on the existing destructive `burnRedactions` path in
+  `@ingcreators/annot-mcp`. Phase 3a's annotation yaml rejects
+  `style: "mosaic" | "blur"` accordingly.
+
+  **Compatibility** — additive. Existing `BboxAnnotation` callers
+  keep working; the new variants are opt-in by setting
+  `type: "freehand" | "focusMask"`.
+
+- 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.
+
+- 691bec5: **Add `flattenEditablePng(pngBytes) → pngBytes`** — Phase 3j of
+  `docs/plans/living-spec-authoring-roadmap.md` (Phase 3
+  follow-up #2). The editor's editable-PNG format embeds the
+  original un-annotated capture + the annotations SVG in PNG
+  ancillary chunks for re-edit; "flatten" drops those chunks and
+  keeps just the visible (already-annotated) bytes.
+
+  ### `@ingcreators/annot-annotator` — new public surface
+
+  ```ts
+  import { flattenEditablePng } from "@ingcreators/annot-annotator";
+
+  const flat = flattenEditablePng(editablePngBytes);
+  // → flat PNG: same visible pixels, no Adobe XMP iTXt chunk,
+  //   no custom svGo chunk. `readEditablePngBytes(flat)` returns
+  //   null. File size drops significantly (the editable layer
+  //   roughly doubled the bytes).
+  ```
+
+  ### `@ingcreators/annot-core/xmp-bytes` — new public surface
+
+  The implementation lives in `@ingcreators/annot-core` as
+  `stripPngEditableLayer` — the same chunk-walking helper that
+  `writePngWithMetadata` / `writePngWithTagsOnly` already used
+  internally to clean stale metadata before re-injecting. Now
+  exported so other Tier A consumers (not just annotator) can
+  use it directly.
+
+  annotator's `flattenEditablePng` is a one-line wrapper that
+  calls `stripPngEditableLayer` under a more user-facing name.
+
+  ### Why this is metadata removal, not re-rasterization
+
+  `toEditablePng` rasterizes the SVG fragment onto the base image
+  FIRST and embeds the editable layer as ancillary PNG chunks
+  (`iTXt` carrying Adobe XMP + custom `svGo` chunk). The visible
+  bytes are already the annotated bitmap. Flattening strips the
+  ancillary chunks; the IDAT pixel data stays byte-identical.
+  No decode, no re-encode, no `@napi-rs/canvas` round-trip.
+
+  ### Use cases
+  - **Publish-flat** — editor session → distribution-ready PNG;
+    the editable layer is dead weight for downstream consumers
+    (Slack drop, third-party viewers).
+  - **File size** — editable PNG roughly doubles in bytes
+    (original + SVG embedded); flattening drops the overhead.
+  - **Privacy hardening** — `burnRedactions` is the strong
+    version for _redact_ regions; flattening drops the
+    recoverable original entirely for _all_ annotations,
+    including non-redact ones whose annotated visual the
+    publisher wants to keep but whose original capture they
+    don't want shippable.
+
+  ### Internal rename in annot-core
+
+  The private `removePngMetadata` helper in
+  `@ingcreators/annot-core/xmp-bytes` is renamed to
+  `stripPngEditableLayer` (clearer name describing what it does
+  rather than how it's used). Internal callers in the same
+  module updated. No external API change for the rename itself;
+  `writePngWithMetadata` + `writePngWithTagsOnly` keep their
+  existing signatures + behaviour.
+
+  ### Compatibility
+
+  Additive on annotator + core. No behaviour change for existing
+  callers (the only internal rename is a private helper).
+
+- 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.
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/annotator.d.ts

@@ -22,19 +22,27 @@ export interface AnnotatorInput {
 }
 /**
  * Input for {@link Annotator.toEditablePng}. Same shape as
- * {@link AnnotatorInput} plus optional opaque kv `tags` written into
- * the embedded XMP for provenance / debugging.
+ * {@link AnnotatorInput} plus optional opaque kv `tags` and the
+ * schema-2.0 provenance fields written into the embedded XMP.
  *
- * Soft-convention key names (not validated by the writer; documented
- * in `@ingcreators/annot-core/xmp-bytes`'s `WELL_KNOWN_TAG_KEYS`):
- * - `source` — what produced the PNG (`"docs-tour"`, `"playwright-fixture"`, `"annot-mcp"`).
- * - `screen` — for living-product-docs, the `<Screen id>` value.
- * - `capturedAt` — ISO timestamp.
- * - `commit` — git SHA when applicable.
+ * Since XMP schema 2.0 (`docs/metadata-format.md`), provenance has
+ * first-class fields — prefer `sourceUrl` / `createdAt` / `producer`
+ * / `dpr` over smuggling the equivalent through `tags` (`source` /
+ * `capturedAt` from the old `WELL_KNOWN_TAG_KEYS` convention).
+ * `screen` / `commit` remain tags.
  */
 export interface EditableInput extends AnnotatorInput {
     /** Optional opaque kv tags. */
     tags?: Record<string, string>;
+    /** URL of the captured page, when applicable. */
+    sourceUrl?: string;
+    /** ISO timestamp of the capture moment. */
+    createdAt?: string;
+    /** What produced the PNG (`"annotator"` / `"mcp"` / `"playwright"`
+     *  / a caller-supplied identifier). Defaults to `"annotator"`. */
+    producer?: string;
+    /** devicePixelRatio at capture time, when known. */
+    dpr?: number;
 }
 /** Annotator construction options. All optional. */
 export interface AnnotatorOptions {

package/dist/diff-aggregate.d.ts

@@ -0,0 +1,6 @@
+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[];

package/dist/diff.d.ts

@@ -0,0 +1,30 @@
+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 caller has to capture both at the same
+ * viewport for the comparison to make sense.
+ */
+export declare function diffScreenshots(before: Uint8Array, after: Uint8Array, options?: DiffOptions): Promise<DiffResult>;

package/dist/dsl/schema.d.ts

@@ -206,6 +206,74 @@ export declare const BBOX_ANNOTATION_SCHEMA: {
                 type: string;
             };
         };
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            path: {
+                type: string;
+                minLength: number;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            fill: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            cutout: {
+                $ref: string;
+            };
+            imageWidth: {
+                type: string;
+                minimum: number;
+            };
+            imageHeight: {
+                type: string;
+                minimum: number;
+            };
+            dimColor: {
+                type: string;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            fill: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
     } | {
         type: string;
         required: string[];

package/dist/dsl/types.d.ts

@@ -98,7 +98,47 @@ export interface RawAnnotation {
     type: "raw";
     svgFragment: string;
 }
-export type BboxAnnotation = BboxRectAnnotation | BboxCircleAnnotation | BboxArrowAnnotation | BboxTextAnnotation | BboxCalloutAnnotation | BboxNumberedBadgeAnnotation | RawAnnotation;
+/**
+ * Free-form path. The `path` field carries the SVG `<path>` d
+ * attribute verbatim — `M` / `L` / `C` / `Q` / `Z` commands.
+ *
+ * Style fields are interpreted as stroke-only by default
+ * (`fill: "none"` unless overridden) so a freehand stroke
+ * doesn't accidentally fill its own enclosed area.
+ *
+ * Phase 3b of
+ * [`docs/plans/living-spec-authoring-roadmap.md`](../../../../docs/plans/living-spec-authoring-roadmap.md).
+ */
+export type BboxFreehandAnnotation = AnnotationStyle & {
+    type: "freehand";
+    path: string;
+};
+/**
+ * Focus mask — dim the entire image area EXCEPT the cutout
+ * region. The cutout draws crisp; everything outside is filled
+ * with `dimColor` (default `rgba(0,0,0,0.5)`).
+ *
+ * Implemented as a single `<path>` element with `fill-rule="evenodd"`
+ * combining a full-image rect with the cutout rect: the
+ * even-odd rule cancels overlap, leaving the cutout area
+ * transparent on top of the dimmed background.
+ *
+ * `imageWidth` / `imageHeight` are required so the outer rect
+ * covers the full screenshot; the renderer rejects a partial
+ * focus mask. Phase 3b of
+ * [`docs/plans/living-spec-authoring-roadmap.md`](../../../../docs/plans/living-spec-authoring-roadmap.md).
+ */
+export type BboxFocusMaskAnnotation = AnnotationStyle & {
+    type: "focusMask";
+    /** The crisp cutout region. */
+    cutout: BBox;
+    /** Full-image dimensions — required so the outer rect covers everything. */
+    imageWidth: number;
+    imageHeight: number;
+    /** CSS colour for the dim layer. Default `rgba(0,0,0,0.5)`. */
+    dimColor?: string;
+};
+export type BboxAnnotation = BboxRectAnnotation | BboxCircleAnnotation | BboxArrowAnnotation | BboxTextAnnotation | BboxCalloutAnnotation | BboxNumberedBadgeAnnotation | BboxFreehandAnnotation | BboxFocusMaskAnnotation | RawAnnotation;
 export type RedactStyle = "solid" | "mosaic" | "blur";
 export interface BboxRedactRegion {
     bbox: BBox;

package/dist/flatten-editable-png.d.ts

@@ -0,0 +1,37 @@
+/**
+ * "Burn" an editable PNG into a flat one — drop the editor's
+ * editable layer (Adobe XMP iTXt + custom `svGo` chunk) while
+ * keeping the visible bitmap byte-identical.
+ *
+ * The editable PNG format embeds:
+ *
+ *   - **visible bytes** — the annotated raster the user sees.
+ *   - **Adobe XMP iTXt chunk** — `<annot:annotations>` (the SVG
+ *     layer) + `<annot:tags>` (provenance) for re-edit.
+ *   - **custom `svGo` chunk** — the original un-annotated capture
+ *     for re-edit.
+ *
+ * Flattening strips the iTXt + svGo chunks. The result is a
+ * regular PNG with the same visible pixels but no recoverable
+ * original / no SVG layer. Re-opening in the editor shows the
+ * annotated capture as a non-editable bitmap;
+ * `readEditablePngBytes` returns `null`.
+ *
+ * Use cases:
+ *
+ *   - **Publish-flat** — editor session → distribution-ready
+ *     PNG; the editable layer is dead weight for downstream
+ *     consumers (Slack drop, third-party viewers).
+ *   - **File size** — editable PNG roughly doubles in bytes
+ *     (original + SVG); flattening drops the overhead.
+ *   - **Privacy hardening** — `burnRedactions` is the strong
+ *     version for *redact* regions; flattening drops the
+ *     recoverable original entirely for *all* annotations,
+ *     including non-redact ones whose annotated visual the
+ *     publisher wants to keep but whose original capture
+ *     they don't want shippable.
+ *
+ * Pure data — no DOM, no canvas. Returns input bytes unchanged
+ * when no editable-layer chunks are present (idempotent).
+ */
+export declare function flattenEditablePng(pngBytes: Uint8Array): Uint8Array;

package/dist/index.d.ts

@@ -2,7 +2,11 @@ export { type Annotator, type AnnotatorInput, type AnnotatorOptions, createAnnot
 export { decodeAndEncodeImage, encodeRgba } from './encode/encode.js';
 export { type BrowserEncodeResult, computeResizeTarget, DEFAULT_ENCODE_OPTIONS, type EncodeFormat, type EncodeOptions, type EncodeResult, SAVE_SIZE_LABEL, SAVE_SIZE_MAX_WIDTH, type SaveSizePreset, } from './encode/options.js';
 export { isPhotoHeavy } from './encode/quantize.js';
+export { burnRedactions, burnRegions, type RedactRegion } from './redact-burn.js';
+export { type DiffOptions, type DiffResult, DimensionMismatchError, diffScreenshots, } from './diff.js';
+export { aggregateDiffRegions } from './diff-aggregate.js';
+export { flattenEditablePng } from './flatten-editable-png.js';
 export { BBOX_ANNOTATION_SCHEMA, BBOX_REDACT_REGION_SCHEMA, SHARED_DEFS, } from './dsl/schema.js';
 export { type ArrowOptions, arrowBetween, type BoundingBox, type RectOptions, rectForBoundingBox, type TextOptions, textAt, } from './dsl/svg-primitives.js';
 export { bboxAnnotationsToSvg } from './dsl/to-svg.js';
-export type { AnnotationStyle, BadgePlacement, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxNumberedBadgeAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Point, RawAnnotation, RedactStyle, } from './dsl/types.js';
+export type { AnnotationStyle, BadgePlacement, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxFocusMaskAnnotation, BboxFreehandAnnotation, BboxNumberedBadgeAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Point, RawAnnotation, RedactStyle, } from './dsl/types.js';