@ingcreators/annot-mcp 0.1.0

package/dist/browser/resolve-locator.d.ts

@@ -0,0 +1,43 @@
+import { BBox, BboxAnnotation, LocatorAnnotation } from '../dsl/types.js';
+export interface PageLike {
+    locator(selector: string): LocatorLike;
+}
+export interface LocatorLike {
+    boundingBox(): Promise<BBox | null>;
+}
+export declare class LocatorResolutionError extends Error {
+    readonly locator: string;
+    constructor(locator: string, message: string);
+}
+/**
+ * Resolve a single locator string to its bounding box. Throws
+ * `LocatorResolutionError` when the locator matches nothing or
+ * lies outside the visible viewport (Playwright returns `null` for
+ * both cases — we can't disambiguate without an extra `.count()`
+ * call, and the error message keeps both possibilities in scope).
+ */
+export declare function resolveLocator(page: PageLike, locator: string): Promise<BBox>;
+/**
+ * Convert a `LocatorAnnotation` to its `BboxAnnotation` equivalent
+ * by resolving any embedded locator strings. Annotation type
+ * dictates the adaptation rule for non-rect shapes:
+ *
+ *   - `rect`     — bbox stands in directly.
+ *   - `circle`   — center = bbox centroid; radius = `min(w,h) / 2`.
+ *   - `arrow`    — each endpoint resolves independently; locator
+ *                  endpoints land at the bbox centroid.
+ *   - `text`     — `at` = bbox top-left, raised one font line so
+ *                  the caption sits above the element.
+ *   - `callout`  — `at` / `atLocator` controls the caption anchor;
+ *                  `targetBbox` / `targetLocator` the rect.
+ *   - `raw`      — passes through unchanged.
+ */
+export declare function resolveLocatorAnnotation(page: PageLike, annotation: LocatorAnnotation): Promise<BboxAnnotation>;
+/**
+ * Resolve every entry in a `LocatorAnnotation[]` against the page,
+ * returning the corresponding `BboxAnnotation[]`. Failures throw
+ * the first `LocatorResolutionError` — callers surface this as a
+ * structured tool error so agents can retry with a corrected
+ * selector.
+ */
+export declare function resolveLocatorAnnotations(page: PageLike, annotations: readonly LocatorAnnotation[]): Promise<BboxAnnotation[]>;

package/dist/compare/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/compare/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 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>;

package/dist/dsl/schema.d.ts

@@ -0,0 +1,466 @@
+/** Common shared subschemas — referenced from `$defs` in each tool's
+ *  inputSchema. Spread these into the tool's `$defs` object at
+ *  registration time. */
+export declare const SHARED_DEFS: {
+    BBox: {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            x: {
+                type: string;
+            };
+            y: {
+                type: string;
+            };
+            width: {
+                type: string;
+                minimum: number;
+            };
+            height: {
+                type: string;
+                minimum: number;
+            };
+        };
+    };
+    Point: {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            x: {
+                type: string;
+            };
+            y: {
+                type: string;
+            };
+        };
+    };
+    Intent: {
+        type: string;
+        enum: string[];
+    };
+    AnnotationStyle: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            fill: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+    };
+    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;
+        properties: {
+            type: {
+                const: string;
+            };
+            bbox: {
+                $ref: string;
+            };
+            locator: {
+                $ref: string;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            fill: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+        anyOf: {
+            required: string[];
+        }[];
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            center: {
+                $ref: string;
+            };
+            radius: {
+                type: string;
+                minimum: number;
+            };
+            locator: {
+                $ref: string;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            fill: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+        anyOf: {
+            required: string[];
+        }[];
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            from: {
+                $ref: string;
+            };
+            fromLocator: {
+                $ref: string;
+            };
+            to: {
+                $ref: string;
+            };
+            toLocator: {
+                $ref: string;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            strokeWidth: {
+                type: string;
+                minimum: number;
+            };
+            color: {
+                type: string;
+            };
+        };
+        allOf: {
+            anyOf: {
+                required: string[];
+            }[];
+        }[];
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            at: {
+                $ref: string;
+            };
+            locator: {
+                $ref: string;
+            };
+            content: {
+                type: string;
+            };
+            fontSize: {
+                type: string;
+                minimum: number;
+            };
+            anchor: {
+                type: string;
+                enum: string[];
+            };
+            intent: {
+                $ref: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+        anyOf: {
+            required: string[];
+        }[];
+    } | {
+        type: string;
+        required: string[];
+        additionalProperties: boolean;
+        properties: {
+            type: {
+                const: string;
+            };
+            at: {
+                $ref: string;
+            };
+            atLocator: {
+                $ref: string;
+            };
+            targetBbox: {
+                $ref: string;
+            };
+            targetLocator: {
+                $ref: string;
+            };
+            content: {
+                type: string;
+            };
+            intent: {
+                $ref: string;
+            };
+            stroke: {
+                type: string;
+            };
+            color: {
+                type: string;
+            };
+        };
+        allOf: {
+            anyOf: {
+                required: string[];
+            }[];
+        }[];
+    })[];
+};
+export declare const BBOX_REDACT_REGION_SCHEMA: {
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        bbox: {
+            $ref: string;
+        };
+        style: {
+            type: string;
+            enum: string[];
+        };
+        color: {
+            type: string;
+        };
+    };
+};
+export declare const LOCATOR_REDACT_REGION_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        bbox: {
+            $ref: string;
+        };
+        locator: {
+            $ref: string;
+        };
+        style: {
+            type: string;
+            enum: string[];
+        };
+        color: {
+            type: string;
+        };
+    };
+    anyOf: {
+        required: string[];
+    }[];
+};

package/dist/dsl/svg-primitives.d.ts

@@ -0,0 +1,34 @@
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface RectOptions {
+    stroke?: string;
+    strokeWidth?: number;
+    fill?: string;
+}
+export interface ArrowOptions {
+    color?: string;
+    strokeWidth?: number;
+}
+export interface TextOptions {
+    color?: string;
+    fontSize?: number;
+    anchor?: "start" | "middle" | "end";
+}
+/** Outline a bounding box with an SVG `<rect>`. */
+export declare function rectForBoundingBox(bbox: BoundingBox, opts?: RectOptions): string;
+/**
+ * Draw an arrow from `from` to `to`. Inlines a unique-id `<marker>`
+ * definition so the helper is self-contained — call it twice and
+ * each call produces a distinct arrowhead marker.
+ */
+export declare function arrowBetween(from: Point, to: Point, opts?: ArrowOptions): string;
+/** Drop a text label at a position. */
+export declare function textAt(at: Point, content: string, opts?: TextOptions): string;

package/dist/dsl/to-svg.d.ts

@@ -0,0 +1,10 @@
+import { BboxAnnotation } from './types.js';
+/**
+ * Convert a list of bbox-flavour annotations into a single SVG
+ * fragment string. The fragment is suitable as the
+ * `annotationsSvg` payload for `@ingcreators/annot-annotator`.
+ *
+ * Phase 1 emits the bare fragments only (no `<svg>` wrapper); the
+ * annotator's sanitiser handles wrapping at rasterise time.
+ */
+export declare function bboxAnnotationsToSvg(annotations: readonly BboxAnnotation[]): string;

package/dist/dsl/types.d.ts

@@ -0,0 +1,126 @@
+/** 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;
+/**
+ * Playwright locator string. Follows the standard locator grammar:
+ * CSS selectors (`button.primary`), text engines (`text=Submit`,
+ * `button:has-text("Submit")`), ARIA roles (`role=button[name="Sign in"]`),
+ * test ids (`[data-testid="email"]`), and chained `>>` operators.
+ */
+export type Locator = string;
+export type LocatorRectAnnotation = AnnotationStyle & {
+    type: "rect";
+    /** Exactly one of `bbox` / `locator` is required. */
+    bbox?: BBox;
+    locator?: Locator;
+};
+export type LocatorCircleAnnotation = AnnotationStyle & {
+    type: "circle";
+    /** Coordinate path. */
+    center?: Point;
+    radius?: number;
+    /** Locator path. Radius derives from `min(width, height) / 2`. */
+    locator?: Locator;
+};
+export type LocatorArrowAnnotation = AnnotationStyle & {
+    type: "arrow";
+    /** Exactly one of `from` / `fromLocator` is required. */
+    from?: Point;
+    fromLocator?: Locator;
+    /** Exactly one of `to` / `toLocator` is required. */
+    to?: Point;
+    toLocator?: Locator;
+};
+export type LocatorTextAnnotation = AnnotationStyle & {
+    type: "text";
+    /** Coordinate path. */
+    at?: Point;
+    /**
+     * Locator path. `at` becomes the bbox top-left, with the text
+     * placed directly above the bbox.
+     */
+    locator?: Locator;
+    content: string;
+    fontSize?: number;
+    anchor?: "start" | "middle" | "end";
+};
+export type LocatorCalloutAnnotation = AnnotationStyle & {
+    type: "callout";
+    /** Coordinate path for the caption anchor. */
+    at?: Point;
+    atLocator?: Locator;
+    /** Coordinate path for the targeted region. */
+    targetBbox?: BBox;
+    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 LocatorRedactRegion = {
+    bbox?: BBox;
+    locator?: Locator;
+    style?: RedactStyle;
+    color?: string;
+};