@ingcreators/annot-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @ingcreators/annot-mcp
 
+## 0.2.0
+
+### Minor Changes
+
+- b3e8e53: Both packages now accept an optional `encode` option that flows through to `@ingcreators/annot-annotator@0.3.0`'s `toEncoded()` / `decodeAndEncodeImage()` pipeline. Achieves feature parity with the Chrome extension's "Save size" + "Format smart" capture settings for AI-agent (`annot-mcp`) and Playwright-test (`annot-playwright`) flows.
+
+  ## `annot-playwright`
+
+  ```ts
+  await annotator.annotateScreenshot(page, {
+    annotations: [...],
+    encode: { format: "smart", saveSizePreset: "standard" },
+  });
+  ```
+
+  Returned bytes shrink to PNG-8 / JPEG / resized PNG-32 per the smart heuristic; default behaviour when `encode` is omitted matches v0.2.x (raw PNG-32 from the annotator).
+
+  ## `annot-mcp`
+
+  All five tools (`annot_annotate_screenshot`, `annot_annotate_url`, `annot_redact_screenshot`, `annot_redact_url`, `annot_compare_screenshots`) accept the same `encode` shape on their MCP `inputSchema`. Agents can specify any subset:
+
+  ```jsonc
+  {
+    "url": "https://...",
+    "annotations": [...],
+    "encode": {
+      "format": "smart",
+      "saveSizePreset": "light",
+      "smartFallback": "jpeg"
+    }
+  }
+  ```
+
+  `format`: `"smart"` (default — PNG-8 for UI / PNG / JPEG for photos) / `"png"` / `"jpeg"`.
+  `saveSizePreset`: `"light"` 1280px / `"standard"` 1920px / `"highQuality"` 2560px / `"original"` no resize.
+  `smartFallback`, `smartColorThreshold`, `jpegPercent` all configurable.
+
+  Output `mimeType` flips to `image/jpeg` when the chosen path emits JPEG, so MCP clients render inline correctly. The text confirmation when `output` is set now includes the chosen format and any `reason` (`png-8` / `photo-fallback-jpeg` / `imagequant-missing` / …) for observability.
+
+  Backwards-compatible: when `encode` is omitted, all tools emit PNG-32 bytes verbatim (no decode/encode round-trip, same as v0.1.x / v0.2.x).
+
+### Patch Changes
+
+- Updated dependencies [86d0853]
+  - @ingcreators/annot-annotator@0.3.0
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [92378f9]
+  - @ingcreators/annot-annotator@0.2.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -17,18 +17,14 @@ browser-driven workflows:
   single MCP call; the server handles capture + locator
   resolution + render.
 
-> **Status:** under construction. Phases 1–5 + 7 of
-> [`docs/plans/agent-mcp-integration.md`](../../docs/plans/agent-mcp-integration.md)
-> have landed; the package is `private: true` in the workspace
-> until Phase 8 (gated on
-> [`docs/plans/headless-annotator-publish.md`](../../docs/plans/headless-annotator-publish.md))
-> flips it for the first npm publish. Phase 6 (PPTX export) is
-> deferred indefinitely per the plan.
+> Phase 6 (PPTX export) is deferred indefinitely per the
+> design plan in
+> [`docs/plans/_done/agent-mcp-integration.md`](../../docs/plans/_done/agent-mcp-integration.md),
+> pending the `pptx-export` `ImageRecord[]`-driven refactor noted
+> in [`CLAUDE.md`](../../CLAUDE.md) §2.
 
 ## Installation
 
-After Phase 8 publish:
-
 ```sh
 # Once globally (or via npx per-call)
 npm install -g @ingcreators/annot-mcp
@@ -329,7 +325,7 @@ The agent sees these as MCP tool errors and can correct + retry.
 - [`docs/ai-agents.md`](../../docs/ai-agents.md) — short intro
   guide + "which doc do I want?" map; start here if you're new
   to the MCP integration.
-- [`docs/plans/agent-mcp-integration.md`](../../docs/plans/agent-mcp-integration.md)
+- [`docs/plans/_done/agent-mcp-integration.md`](../../docs/plans/_done/agent-mcp-integration.md)
   — full design + phase ledger.
 - [`@ingcreators/annot-annotator`](../annotator/README.md) — the
   underlying Tier A headless renderer.

package/dist/dsl/schema.d.ts

@@ -1,7 +1,15 @@
-/** Common shared subschemas — referenced from `$defs` in each tool's
- *  inputSchema. Spread these into the tool's `$defs` object at
- *  registration time. */
+export { BBOX_ANNOTATION_SCHEMA, BBOX_REDACT_REGION_SCHEMA, } from '@ingcreators/annot-annotator';
+/**
+ * `$defs` to spread into every MCP tool inputSchema. Combines the
+ * annotator's bbox-flavour `SHARED_DEFS` (`BBox`, `Point`,
+ * `Intent`, `AnnotationStyle`) with the mcp-only `Locator` shape
+ * referenced by every `LOCATOR_*` schema in this file.
+ */
 export declare const SHARED_DEFS: {
+    Locator: {
+        type: string;
+        minLength: number;
+    };
     BBox: {
         type: string;
         required: string[];
@@ -62,184 +70,9 @@ export declare const SHARED_DEFS: {
             };
         };
     };
-    Locator: {
-        type: string;
-        minLength: number;
-    };
-};
-export declare const BBOX_ANNOTATION_SCHEMA: {
-    oneOf: ({
-        type: string;
-        required: string[];
-        additionalProperties: boolean;
-        properties: {
-            type: {
-                const: string;
-            };
-            bbox: {
-                $ref: string;
-            };
-            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;
-            };
-            center: {
-                $ref: string;
-            };
-            radius: {
-                type: string;
-                minimum: 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;
-            };
-            from: {
-                $ref: string;
-            };
-            to: {
-                $ref: string;
-            };
-            intent: {
-                $ref: string;
-            };
-            stroke: {
-                type: string;
-            };
-            strokeWidth: {
-                type: string;
-                minimum: number;
-            };
-            color: {
-                type: string;
-            };
-        };
-    } | {
-        type: string;
-        required: string[];
-        additionalProperties: boolean;
-        properties: {
-            type: {
-                const: string;
-            };
-            at: {
-                $ref: string;
-            };
-            content: {
-                type: string;
-            };
-            fontSize: {
-                type: string;
-                minimum: number;
-            };
-            anchor: {
-                type: string;
-                enum: string[];
-            };
-            intent: {
-                $ref: string;
-            };
-            color: {
-                type: string;
-            };
-        };
-    } | {
-        type: string;
-        required: string[];
-        additionalProperties: boolean;
-        properties: {
-            type: {
-                const: string;
-            };
-            at: {
-                $ref: string;
-            };
-            targetBbox: {
-                $ref: string;
-            };
-            content: {
-                type: string;
-            };
-            intent: {
-                $ref: string;
-            };
-            stroke: {
-                type: string;
-            };
-            color: {
-                type: string;
-            };
-        };
-    } | {
-        type: string;
-        required: string[];
-        additionalProperties: boolean;
-        properties: {
-            type: {
-                const: string;
-            };
-            svgFragment: {
-                type: string;
-            };
-        };
-    })[];
 };
 export declare const LOCATOR_ANNOTATION_SCHEMA: {
     oneOf: ({
-        type: string;
-        required: string[];
-        additionalProperties: boolean;
-        properties: {
-            type: {
-                const: string;
-            };
-            svgFragment: {
-                type: string;
-            };
-        };
-    } | {
         type: string;
         required: string[];
         additionalProperties: boolean;
@@ -423,22 +256,49 @@ export declare const LOCATOR_ANNOTATION_SCHEMA: {
                 required: string[];
             }[];
         }[];
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            svgFragment: {
+                type: string;
+            };
+        };
     })[];
 };
-export declare const BBOX_REDACT_REGION_SCHEMA: {
+export declare const ENCODE_OPTIONS_SCHEMA: {
     type: string;
-    required: string[];
     additionalProperties: boolean;
     properties: {
-        bbox: {
-            $ref: string;
+        format: {
+            type: string;
+            enum: string[];
+            description: string;
         };
-        style: {
+        saveSizePreset: {
             type: string;
             enum: string[];
+            description: string;
         };
-        color: {
+        smartFallback: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        smartColorThreshold: {
+            type: string;
+            minimum: number;
+            description: string;
+        };
+        jpegPercent: {
             type: string;
+            minimum: number;
+            maximum: number;
+            description: string;
         };
     };
 };

package/dist/dsl/types.d.ts

@@ -1,62 +1,5 @@
-/** Axis-aligned bounding box. Coordinates are page pixels. */
-export interface BBox {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** Point in page pixels. */
-export interface Point {
-    x: number;
-    y: number;
-}
-/**
- * Semantic colour shorthand. Resolves to the Annot design system's
- * matching token (e.g. `intent: "error"` → `--annot-color-error`).
- * Explicit `stroke` / `color` / `fill` on an annotation override
- * the intent-derived defaults.
- */
-export type Intent = "info" | "warning" | "error" | "success" | "neutral";
-/** Style overrides shared across most annotation shapes. */
-export interface AnnotationStyle {
-    intent?: Intent;
-    stroke?: string;
-    strokeWidth?: number;
-    fill?: string;
-    color?: string;
-}
-export type BboxRectAnnotation = AnnotationStyle & {
-    type: "rect";
-    bbox: BBox;
-};
-export type BboxCircleAnnotation = AnnotationStyle & {
-    type: "circle";
-    center: Point;
-    radius: number;
-};
-export type BboxArrowAnnotation = AnnotationStyle & {
-    type: "arrow";
-    from: Point;
-    to: Point;
-};
-export type BboxTextAnnotation = AnnotationStyle & {
-    type: "text";
-    at: Point;
-    content: string;
-    fontSize?: number;
-    anchor?: "start" | "middle" | "end";
-};
-export type BboxCalloutAnnotation = AnnotationStyle & {
-    type: "callout";
-    at: Point;
-    targetBbox: BBox;
-    content: string;
-};
-export interface RawAnnotation {
-    type: "raw";
-    svgFragment: string;
-}
-export type BboxAnnotation = BboxRectAnnotation | BboxCircleAnnotation | BboxArrowAnnotation | BboxTextAnnotation | BboxCalloutAnnotation | RawAnnotation;
+import { AnnotationStyle, BBox, Point } from '@ingcreators/annot-annotator';
+export type { AnnotationStyle, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Point, RawAnnotation, RedactStyle, } from '@ingcreators/annot-annotator';
 /**
  * Playwright locator string. Follows the standard locator grammar:
  * CSS selectors (`button.primary`), text engines (`text=Submit`,
@@ -110,17 +53,13 @@ export type LocatorCalloutAnnotation = AnnotationStyle & {
     targetLocator?: Locator;
     content: string;
 };
-export type LocatorAnnotation = LocatorRectAnnotation | LocatorCircleAnnotation | LocatorArrowAnnotation | LocatorTextAnnotation | LocatorCalloutAnnotation | RawAnnotation;
-export type RedactStyle = "solid" | "mosaic" | "blur";
-export interface BboxRedactRegion {
-    bbox: BBox;
-    style?: RedactStyle;
-    /** CSS colour, applied only when `style` is `"solid"`. */
-    color?: string;
-}
+export type LocatorAnnotation = LocatorRectAnnotation | LocatorCircleAnnotation | LocatorArrowAnnotation | LocatorTextAnnotation | LocatorCalloutAnnotation | {
+    type: "raw";
+    svgFragment: string;
+};
 export type LocatorRedactRegion = {
     bbox?: BBox;
     locator?: Locator;
-    style?: RedactStyle;
+    style?: import('@ingcreators/annot-annotator').RedactStyle;
     color?: string;
 };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
+export { arrowBetween, bboxAnnotationsToSvg, rectForBoundingBox, textAt, } from '@ingcreators/annot-annotator';
 export { type CapturePageOptions, type CapturePageResult, capturePage, type PageHandle, type ViewportOptions, } from './browser/capture.js';
 export { type BrowserLauncher, type BrowserLike, BrowserPool, type BrowserPoolOptions, ChromiumUnavailableError, createChromiumPool, } from './browser/pool.js';
 export { type LocatorLike, LocatorResolutionError, type PageLike, resolveLocator, resolveLocatorAnnotation, resolveLocatorAnnotations, } from './browser/resolve-locator.js';
 export { aggregateDiffRegions } from './compare/aggregate.js';
 export { type DiffOptions, type DiffResult, DimensionMismatchError, diffScreenshots, } from './compare/diff.js';
 export { BBOX_ANNOTATION_SCHEMA, BBOX_REDACT_REGION_SCHEMA, LOCATOR_ANNOTATION_SCHEMA, LOCATOR_REDACT_REGION_SCHEMA, SHARED_DEFS, } from './dsl/schema.js';
-export { bboxAnnotationsToSvg } from './dsl/to-svg.js';
 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';