@ingcreators/annot-annotator 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @ingcreators/annot-annotator
 
+## 0.3.0
+
+### Minor Changes
+
+- 86d0853: `Annotator.toEncoded(input, encodeOptions?)` — new async method that combines rasterise + smart-encode in one step. Achieves feature parity with Chrome extension's "Save size" + "Format smart" capture options for the manual-creation / agent use cases.
+
+  **EncodeOptions** (re-exported from `@ingcreators/annot-core/encode/options`):
+  - `format: "smart" | "png" | "jpeg"` — Smart picks PNG-8 for UI-heavy content (via libimagequant) and JPEG / PNG-32 for photo-heavy content per `smartFallback`. PNG / JPEG paths skip the smart heuristic.
+  - `saveSizePreset: "light" | "standard" | "highQuality" | "original"` — Max-width caps at 1280 / 1920 / 2560 / no-resize. Aspect-preserving; never upscales.
+  - `smartFallback: "png" | "jpeg"` — Photo-heavy fallback format.
+  - `smartColorThreshold: number` — Unique-colour count threshold (default 15000). Above this the image is treated as photo-heavy.
+  - `jpegPercent: number` — JPEG quality 60–100 (default 92).
+
+  Returns `{ bytes, chosen, reason?, width, height }` so callers can log which format was actually chosen (`"png-8"` / `"photo-fallback-jpeg"` / `"imagequant-missing"` etc.).
+
+  Standalone `encodeRgba(rgba, width, height, options)` also exported for callers who already have raw RGBA bytes (e.g. from a Playwright screenshot fed through their own canvas).
+
+  **New runtime dependencies:**
+  - `@napi-rs/canvas` (regular `dependencies`) — native canvas binding for PNG / JPEG encoding + resize. ~20 MB platform-matched binary at install time.
+  - `@ingcreators/annot-imagequant` (regular `dependencies`) — GPL-3.0 WASM wrapper around libimagequant for PNG-8 quantization. Loaded via dynamic import; consumers who explicitly uninstall the package to avoid the GPL inclusion get a graceful fallback to PNG-32 (`reason: "imagequant-missing"`).
+  - `pako` (regular `dependencies`) — pulled in transitively via the PNG-8 encoder; declared explicitly so consumer installs are deterministic.
+
+  The existing `toPng()` and `toSvg()` methods are unchanged — `toEncoded()` is purely additive.
+
+### Patch Changes
+
+- Updated dependencies [adae49d]
+  - @ingcreators/annot-imagequant@0.1.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 92378f9: Public DSL surface (since 0.2.0). The annotation DSL that was previously private to `@ingcreators/annot-mcp` now lives on the annotator package so any Annot consumer (test runtimes, AI agents, plugin authors) can use the same vocabulary.
+
+  New exports:
+  - Types: `BBox`, `Point`, `Intent`, `AnnotationStyle`, `BboxAnnotation` (`rect` / `circle` / `arrow` / `text` / `callout` / `raw`), `RawAnnotation`, `BboxRedactRegion`, `RedactStyle`.
+  - Converter: `bboxAnnotationsToSvg(annotations)` returns the SVG fragment string `createAnnotator(...).toPng({ annotationsSvg })` accepts.
+  - SVG primitives: `rectForBoundingBox`, `arrowBetween`, `textAt`, plus `BoundingBox` / `RectOptions` / `ArrowOptions` / `TextOptions`.
+  - JSON Schemas: `SHARED_DEFS`, `BBOX_ANNOTATION_SCHEMA`, `BBOX_REDACT_REGION_SCHEMA` (drop into MCP tool `inputSchema` `$defs` blocks).
+
+  The `intent` shorthand (`"info"` / `"warning"` / `"error"` / `"success"` / `"neutral"`) resolves to the Annot design system's semantic colour tokens automatically — no more thinking in raw hex values.
+
+  Marker id prefix in `arrowBetween` changed from `annot-pw-arrow-N` (previous helper in `@ingcreators/annot-playwright`) / `annot-mcp-arrow-N` (previous helper in `@ingcreators/annot-mcp`) to the package-neutral `annot-arrow-N`. Snapshot-on-SVG tests should expect this minor cosmetic delta.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -1,18 +1,17 @@
 # `@ingcreators/annot-annotator`
 
+[![npm](https://img.shields.io/npm/v/@ingcreators/annot-annotator.svg)](https://www.npmjs.com/package/@ingcreators/annot-annotator)
+[![license](https://img.shields.io/npm/l/@ingcreators/annot-annotator.svg)](https://github.com/ingcreators/annot/blob/main/LICENSE)
+
 Headless annotator — produce annotated screenshots from Node without
 a browser. Reads an `ImageRecord`-shaped input (base image + saved
 annotations SVG) and emits a PNG or the merged SVG.
 
-> **Status:** Workspace package, not yet published to npm. The public
-> API is stable; the package becomes installable in Phase 3 of the
-> headless-annotator track (gated on Changesets).
->
-> Companion package: `@ingcreators/annot-playwright` (Phase 2 of the
-> same track) — a Playwright fixture composing this annotator into
-> idiomatic `test.extend({ annotator })` form.
+Companion package: [`@ingcreators/annot-playwright`](https://www.npmjs.com/package/@ingcreators/annot-playwright) —
+a Playwright fixture composing this annotator into idiomatic
+`test.extend({ annotator })` form.
 
-## Install (post-publish)
+## Install
 
 ```sh
 npm install @ingcreators/annot-annotator
@@ -20,6 +19,10 @@ npm install @ingcreators/annot-annotator
 pnpm add @ingcreators/annot-annotator
 ```
 
+Peer runtime requirements: Node 20+. The package depends on
+`@resvg/resvg-js` (native binding via `@napi-rs`) — npm install
+fetches the platform-matched prebuild automatically.
+
 ## Usage
 
 ```ts

package/dist/annotator.d.ts

@@ -1,3 +1,5 @@
+import { EncodeOptions } from '@ingcreators/annot-core/encode/options';
+import { EncodeResult } from './encode/options.js';
 /**
  * Structural shape the annotator accepts. A real `ImageRecord`
  * from `@ingcreators/annot-core/storage` satisfies this — the
@@ -47,16 +49,23 @@ export interface AnnotatorOptions {
     defaultFontFamily?: string;
 }
 /**
- * Annotator instance returned by {@link createAnnotator}. Use
- * `toPng` to rasterise; use `toSvg` to get the merged SVG without
- * rasterisation (useful for piping into another tool, or for
- * inspecting what the annotator would render).
+ * Annotator instance returned by {@link createAnnotator}.
+ *
+ * - {@link toPng}     synchronous rasterise → PNG-32 bytes.
+ * - {@link toSvg}     build the rasterise-ready SVG string (no
+ *                     rasterisation).
+ * - {@link toEncoded} (since 0.3.0) async rasterise + smart
+ *                     encode pipeline — `saveSizePreset` resize,
+ *                     `format: "smart" | "png" | "jpeg"` decision
+ *                     tree, PNG-8 quantization via the optional
+ *                     `@ingcreators/annot-imagequant`.
  */
 export interface Annotator {
     /**
-     * Rasterise the input to a PNG byte array. JPEG output is not
-     * yet supported — Phase 1.5 brings `sharp` as an optional peer
-     * dep.
+     * Rasterise the input to a PNG-32 byte array. Synchronous, no
+     * resize, no smart format selection — the most direct path.
+     * Use {@link toEncoded} when you need `saveSize` / format
+     * decisions.
      */
     toPng(input: AnnotatorInput): Uint8Array;
     /**
@@ -65,6 +74,21 @@ export interface Annotator {
      * the caller can feed to any other SVG tool.
      */
     toSvg(input: AnnotatorInput): string;
+    /**
+     * Rasterise + encode in one step. Honours `saveSizePreset`
+     * (max-width resize), `format` (`"smart"` / `"png"` /
+     * `"jpeg"`), and `jpegPercent`. Returns the encoded bytes plus
+     * a metadata record so the caller can log which format was
+     * actually picked.
+     *
+     * Smart mode requires `@ingcreators/annot-imagequant` to be
+     * available at runtime for PNG-8 output; the WASM ships as a
+     * regular `dependencies` entry but is dynamic-imported, so a
+     * consumer who explicitly uninstalls the package (to avoid
+     * its GPL-3.0 license) gets a graceful fallback to PNG-32
+     * with `reason: "imagequant-missing"`.
+     */
+    toEncoded(input: AnnotatorInput, encodeOptions?: EncodeOptions): Promise<EncodeResult>;
 }
 /**
  * Construct a headless annotator. Options are forwarded to the

package/dist/dsl/schema.d.ts

@@ -0,0 +1,239 @@
+/** Common subschemas to spread into a tool's `$defs` block. */
+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;
+            };
+        };
+    };
+};
+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 BBOX_REDACT_REGION_SCHEMA: {
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        bbox: {
+            $ref: string;
+        };
+        style: {
+            type: string;
+            enum: string[];
+        };
+        color: {
+            type: string;
+        };
+    };
+};

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

@@ -0,0 +1,32 @@
+import { BBox, Point } from './types.js';
+/**
+ * Back-compat alias retained because the original
+ * `@ingcreators/annot-playwright` helpers exposed this name.
+ * Prefer importing `BBox` from `@ingcreators/annot-annotator`
+ * directly.
+ */
+export type BoundingBox = BBox;
+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,11 @@
+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 `createAnnotator(...).toPng()` /
+ * `.toSvg()`.
+ *
+ * Emits bare fragments (no outer `<svg>` wrapper); the annotator's
+ * sanitiser wraps them at rasterise time.
+ */
+export declare function bboxAnnotationsToSvg(annotations: readonly BboxAnnotation[]): string;

package/dist/dsl/types.d.ts

@@ -0,0 +1,66 @@
+/** 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;
+export type RedactStyle = "solid" | "mosaic" | "blur";
+export interface BboxRedactRegion {
+    bbox: BBox;
+    style?: RedactStyle;
+    /** CSS colour, applied only when `style` is `"solid"`. */
+    color?: string;
+}

package/dist/encode/encode.d.ts

@@ -0,0 +1,37 @@
+import { EncodeOptions } from '@ingcreators/annot-core/encode/options';
+import { EncodeResult } from './options.js';
+/**
+ * Encode raw RGBA pixels per the requested {@link EncodeOptions}.
+ *
+ * Algorithm (mirrors the browser-side pipeline):
+ *
+ *   1. Resize the source via `saveSizePreset` (aspect-preserving;
+ *      never upscale).
+ *   2. Branch on `format`:
+ *        - `"png"`  → PNG-32 encode (lossless).
+ *        - `"jpeg"` → JPEG encode at `jpegPercent`.
+ *        - `"smart"`:
+ *            - If pixel count > `MAX_SMART_PIXELS`, return PNG-32
+ *              with `reason: "too-large-for-png8"`.
+ *            - Sample unique-colour count via {@link isPhotoHeavy}.
+ *              If photo-heavy, emit `smartFallback` (PNG-32 or
+ *              JPEG) with reason `"photo-fallback-*"`.
+ *            - Otherwise quantize to ≤256 colours via libimagequant
+ *              (if installed) and emit PNG-8 with reason `"png-8"`.
+ *              When the optional imagequant WASM isn't installed,
+ *              fall back to PNG-32 with `reason: "imagequant-missing"`.
+ */
+export declare function encodeRgba(rgba: Uint8Array, width: number, height: number, options?: EncodeOptions): Promise<EncodeResult>;
+/**
+ * Decode a PNG / JPEG byte stream into RGBA and re-encode it
+ * through {@link encodeRgba}. Useful for downstream pipelines
+ * that emit a PNG first (e.g. the redact-burn output or a
+ * Playwright `page.screenshot()` capture) and want to apply
+ * `saveSize` / `format` after the fact.
+ *
+ * The decode goes through `@napi-rs/canvas`'s `loadImage`, so
+ * any format the underlying Skia decoder understands (PNG /
+ * JPEG / WebP / AVIF on the canvas's supported list) flows
+ * through transparently.
+ */
+export declare function decodeAndEncodeImage(imageBytes: Uint8Array, options?: EncodeOptions): Promise<EncodeResult>;

package/dist/encode/options.d.ts

@@ -0,0 +1,19 @@
+export type { EncodeFormat, EncodeOptions, EncodeResult as BrowserEncodeResult, SaveSizePreset, } from '@ingcreators/annot-core/encode/options';
+export { computeResizeTarget, DEFAULT_ENCODE_OPTIONS, SAVE_SIZE_LABEL, SAVE_SIZE_MAX_WIDTH, } from '@ingcreators/annot-core/encode/options';
+/**
+ * Node-side encode result. Returns raw bytes (vs the browser-side
+ * counterpart returning a `data:` URL string) — agents and test
+ * runtimes typically want bytes to attach to GitHub issues / test
+ * reports / write to disk.
+ */
+export interface EncodeResult {
+    /** Encoded image bytes (PNG-8 / PNG-32 / JPEG depending on `chosen`). */
+    bytes: Uint8Array;
+    /** Actual format chosen (may differ from requested in smart mode). */
+    chosen: "png" | "jpeg";
+    /** Human-readable note (`"png-8"` / `"photo-fallback-jpeg"` / …). */
+    reason?: string;
+    /** Final pixel dimensions after `saveSizePreset` resize. */
+    width: number;
+    height: number;
+}

package/dist/encode/quantize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Quantize RGBA pixels to ≤256 colours via libimagequant and emit
+ * a PNG-8 file. Returns the encoded bytes, OR `null` if the
+ * optional imagequant module isn't installed.
+ *
+ * The caller is responsible for falling back to a non-PNG-8 path
+ * (PNG-32 or JPEG) when this returns `null`.
+ */
+export declare function quantizeRgbaToPng8(rgba: Uint8Array, width: number, height: number): Promise<Uint8Array | null>;
+/**
+ * Heuristic: does this image look photo-heavy?
+ *
+ * Samples ~50,000 pixels from the RGBA buffer (stride-walks rather
+ * than reading every pixel — sufficient for the bimodal "UI vs
+ * photo" decision). Returns `true` if the unique-color count
+ * exceeds `threshold`. Typical UI screenshots return <5,000 unique
+ * colours; pages with rich photography return >20,000.
+ */
+export declare function isPhotoHeavy(rgba: Uint8Array, threshold: number): boolean;
+/** Whether the optional imagequant WASM is available at runtime.
+ *  Useful for callers that want to decide ahead of time whether to
+ *  request `format: "smart"`. */
+export declare function isImagequantAvailable(): Promise<boolean>;

package/dist/index.d.ts

@@ -1 +1,8 @@
 export { type Annotator, type AnnotatorInput, type AnnotatorOptions, createAnnotator, } from './annotator.js';
+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 { isImagequantAvailable, isPhotoHeavy } from './encode/quantize.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, BBox, BboxAnnotation, BboxArrowAnnotation, BboxCalloutAnnotation, BboxCircleAnnotation, BboxRectAnnotation, BboxRedactRegion, BboxTextAnnotation, Intent, Point, RawAnnotation, RedactStyle, } from './dsl/types.js';

package/dist/index.js

@@ -1,80 +1,530 @@
-import { Resvg as e } from "@resvg/resvg-js";
-import { DOMParser as t, XMLSerializer as n } from "@xmldom/xmldom";
-//#region ../core/src/editor/svg-format.ts
-var r = "data-annot-version";
-//#endregion
-//#region src/sanitise-svg.ts
-function i(e) {
-	if (!e || e.trim().length === 0) return "";
-	let r = new t(), i;
-	try {
-		i = r.parseFromString(e, "image/svg+xml");
-	} catch {
-		return "";
-	}
-	let o = i.documentElement;
-	if (!o) return "";
-	let s = new n(), c = "";
-	for (let e = 0; e < o.childNodes.length; e++) {
-		let t = o.childNodes.item(e);
-		if (!t || t.nodeType !== 1) continue;
-		let n = t, r = n.localName ?? n.tagName ?? "";
-		if (r === "defs") {
-			let e = a(n);
-			e !== null && (c += s.serializeToString(e));
-			continue;
-		}
-		if (!(r === "image" && !n.getAttribute("data-redact-style")) && n.getAttribute("id") !== "ui-overlay") {
-			if (n.getAttribute("id") === "annotations") {
-				for (let e = 0; e < n.childNodes.length; e++) {
-					let t = n.childNodes.item(e);
-					t && t.nodeType === 1 && (c += s.serializeToString(t));
-				}
-				continue;
-			}
-			c += s.serializeToString(n);
-		}
-	}
-	return c;
-}
-function a(e) {
-	let t = e.cloneNode(!0);
-	for (let e = t.childNodes.length - 1; e >= 0; e--) {
-		let n = t.childNodes.item(e);
-		if (!n || n.nodeType !== 1) continue;
-		let r = n;
-		(r.localName ?? r.tagName ?? "") === "style" && r.hasAttribute("data-annot-fonts") && t.removeChild(n);
-	}
-	return t.childNodes.length === 0 ? null : t;
-}
-//#endregion
-//#region src/annotator.ts
-function o(t = {}) {
-	let n = {
-		loadSystemFonts: t.loadSystemFonts ?? !1,
-		...t.fontFiles ? { fontFiles: t.fontFiles } : {},
-		...t.fontDirs ? { fontDirs: t.fontDirs } : {},
-		...t.defaultFontFamily ? { defaultFontFamily: t.defaultFontFamily } : {}
-	};
-	return {
-		toSvg(e) {
-			return s(e);
-		},
-		toPng(t) {
-			return new e(s(t), {
-				fitTo: {
-					mode: "width",
-					value: t.width
-				},
-				background: "rgba(0, 0, 0, 0)",
-				font: n
-			}).render().asPng();
-		}
-	};
-}
-function s(e) {
-	let t = i(e.annotationsSvg);
-	return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ${r}="1" width="${e.width}" height="${e.height}" viewBox="0 0 ${e.width} ${e.height}"><image href="${e.originalDataUrl}" width="${e.width}" height="${e.height}"/>` + t + "</svg>";
-}
-//#endregion
-export { o as createAnnotator };
+import { Resvg as P } from "@resvg/resvg-js";
+import { loadImage as R, createCanvas as m } from "@napi-rs/canvas";
+import { deflate as L } from "pako";
+import { DOMParser as j, XMLSerializer as q } from "@xmldom/xmldom";
+const W = "1", M = "data-annot-version", X = {
+  light: 1280,
+  standard: 1920,
+  highQuality: 2560,
+  original: null
+}, Se = {
+  light: "Light (1280px)",
+  standard: "Standard (1920px)",
+  highQuality: "High Quality (2560px)",
+  original: "Original"
+}, C = {
+  format: "smart",
+  smartFallback: "png",
+  smartColorThreshold: 15e3,
+  jpegPercent: 92,
+  saveSizePreset: "standard"
+};
+function V(e, t, r) {
+  const n = X[r];
+  if (n === null || e <= n)
+    return { width: e, height: t, scaled: !1 };
+  const o = n / e;
+  return {
+    width: n,
+    height: Math.max(1, Math.round(t * o)),
+    scaled: !0
+  };
+}
+const G = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]), Q = (() => {
+  const e = new Uint32Array(256);
+  for (let t = 0; t < 256; t++) {
+    let r = t;
+    for (let n = 0; n < 8; n++)
+      r = r & 1 ? 3988292384 ^ r >>> 1 : r >>> 1;
+    e[t] = r >>> 0;
+  }
+  return e;
+})();
+function H(e) {
+  let t = 4294967295;
+  for (let r = 0; r < e.length; r++)
+    t = Q[(t ^ e[r]) & 255] ^ t >>> 8;
+  return (t ^ 4294967295) >>> 0;
+}
+function h(e, t) {
+  const r = new Uint8Array(12 + t.length), n = new DataView(r.buffer);
+  n.setUint32(0, t.length, !1);
+  for (let i = 0; i < 4; i++) r[4 + i] = e.charCodeAt(i);
+  r.set(t, 8);
+  const o = r.subarray(4, 8 + t.length);
+  return n.setUint32(8 + t.length, H(o), !1), r;
+}
+function Z(e, t, r, n, o = 9) {
+  if (r <= 0 || n <= 0) throw new Error("encodePng8: invalid dimensions");
+  if (e.length % 4 !== 0)
+    throw new Error("encodePng8: palette must be RGBA bytes (multiple of 4)");
+  const i = e.length >>> 2;
+  if (i < 1 || i > 256)
+    throw new Error(`encodePng8: palette must have 1–256 colors, got ${i}`);
+  if (t.length !== r * n)
+    throw new Error(
+      `encodePng8: indices length ${t.length} != width*height ${r * n}`
+    );
+  const s = new Uint8Array(13), a = new DataView(s.buffer);
+  a.setUint32(0, r, !1), a.setUint32(4, n, !1), s[8] = 8, s[9] = 3, s[10] = 0, s[11] = 0, s[12] = 0;
+  const c = new Uint8Array(i * 3);
+  let u = !1, f = -1;
+  for (let l = 0; l < i; l++)
+    c[l * 3] = e[l * 4], c[l * 3 + 1] = e[l * 4 + 1], c[l * 3 + 2] = e[l * 4 + 2], e[l * 4 + 3] < 255 && (u = !0, f = l);
+  let g = null;
+  if (u) {
+    g = new Uint8Array(f + 1);
+    for (let l = 0; l <= f; l++) g[l] = e[l * 4 + 3];
+  }
+  const A = r + 1, x = new Uint8Array(A * n);
+  for (let l = 0; l < n; l++) {
+    const T = l * A;
+    x[T] = 0, x.set(t.subarray(l * r, l * r + r), T + 1);
+  }
+  const U = L(x, { level: o, memLevel: 9, windowBits: 15 }), d = [G, h("IHDR", s), h("PLTE", c)];
+  g && d.push(h("tRNS", g)), d.push(h("IDAT", U)), d.push(h("IEND", new Uint8Array(0)));
+  let I = 0;
+  for (const l of d) I += l.length;
+  const S = new Uint8Array(I);
+  let v = 0;
+  for (const l of d)
+    S.set(l, v), v += l.length;
+  return S;
+}
+let w = null;
+async function N() {
+  return w || (w = (async () => {
+    try {
+      const e = await import("@ingcreators/annot-imagequant");
+      return await e.default(), { quantize_image: e.quantize_image };
+    } catch {
+      return null;
+    }
+  })(), w);
+}
+async function J(e, t, r) {
+  const n = await N();
+  if (!n) return null;
+  const o = n.quantize_image(e, t, r, 256);
+  if (!(o?.palette instanceof Uint8Array) || !(o?.indices instanceof Uint8Array))
+    throw new Error("quantize_image returned an unexpected shape");
+  return Z(o.palette, o.indices, t, r, 9);
+}
+function K(e, t) {
+  const r = new Uint32Array(e.buffer, e.byteOffset, e.byteLength >>> 2), n = r.length;
+  if (n === 0) return !1;
+  const i = Math.max(1, Math.floor(n / 5e4)), s = /* @__PURE__ */ new Set();
+  for (let a = 0; a < n; a += i)
+    if (s.add(r[a]), s.size > t) return !0;
+  return !1;
+}
+async function ve() {
+  return await N() !== null;
+}
+const Y = 1e7;
+async function O(e, t, r, n = C) {
+  const o = n.saveSizePreset ?? "original", i = V(t, r, o), s = i.scaled ? ee(e, t, r, i.width, i.height) : e, a = i.width, c = i.height;
+  if (n.format === "png")
+    return { bytes: b(s, a, c), chosen: "png", width: a, height: c };
+  if (n.format === "jpeg")
+    return {
+      bytes: B(s, a, c, n.jpegPercent / 100),
+      chosen: "jpeg",
+      width: a,
+      height: c
+    };
+  if (a * c > Y)
+    return {
+      bytes: b(s, a, c),
+      chosen: "png",
+      reason: "too-large-for-png8",
+      width: a,
+      height: c
+    };
+  if (K(s, n.smartColorThreshold))
+    return n.smartFallback === "jpeg" ? {
+      bytes: B(s, a, c, n.jpegPercent / 100),
+      chosen: "jpeg",
+      reason: "photo-fallback-jpeg",
+      width: a,
+      height: c
+    } : {
+      bytes: b(s, a, c),
+      chosen: "png",
+      reason: "photo-fallback-png",
+      width: a,
+      height: c
+    };
+  const f = await J(s, a, c);
+  return f ? { bytes: f, chosen: "png", reason: "png-8", width: a, height: c } : {
+    bytes: b(s, a, c),
+    chosen: "png",
+    reason: "imagequant-missing",
+    width: a,
+    height: c
+  };
+}
+async function Te(e, t = C) {
+  const r = await R(Buffer.from(e)), o = m(r.width, r.height).getContext("2d");
+  o.drawImage(r, 0, 0);
+  const i = o.getImageData(0, 0, r.width, r.height).data, s = new Uint8Array(i.buffer, i.byteOffset, i.byteLength);
+  return O(s, r.width, r.height, t);
+}
+function b(e, t, r) {
+  const n = m(t, r), o = n.getContext("2d"), i = o.createImageData(t, r);
+  i.data.set(e), o.putImageData(i, 0, 0);
+  const s = n.toBuffer("image/png");
+  return new Uint8Array(s.buffer, s.byteOffset, s.byteLength);
+}
+function B(e, t, r, n) {
+  const o = m(t, r), i = o.getContext("2d"), s = i.createImageData(t, r);
+  s.data.set(e), i.putImageData(s, 0, 0);
+  const a = o.toBuffer("image/jpeg", n);
+  return new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+}
+function ee(e, t, r, n, o) {
+  const i = m(t, r), s = i.getContext("2d"), a = s.createImageData(t, r);
+  a.data.set(e), s.putImageData(a, 0, 0);
+  const u = m(n, o).getContext("2d");
+  u.imageSmoothingEnabled = !0, u.imageSmoothingQuality = "high", u.drawImage(i, 0, 0, t, r, 0, 0, n, o);
+  const g = u.getImageData(0, 0, n, o).data;
+  return new Uint8Array(g.buffer, g.byteOffset, g.byteLength);
+}
+function te(e) {
+  if (!e || e.trim().length === 0)
+    return "";
+  const t = new j();
+  let r;
+  try {
+    r = t.parseFromString(e, "image/svg+xml");
+  } catch {
+    return "";
+  }
+  const n = r.documentElement;
+  if (!n) return "";
+  const o = new q();
+  let i = "";
+  for (let s = 0; s < n.childNodes.length; s++) {
+    const a = n.childNodes.item(s);
+    if (!a || a.nodeType !== 1) continue;
+    const c = a, u = c.localName ?? c.tagName ?? "";
+    if (u === "defs") {
+      const f = re(c);
+      f !== null && (i += o.serializeToString(f));
+      continue;
+    }
+    if (!(u === "image" && !c.getAttribute("data-redact-style")) && c.getAttribute("id") !== "ui-overlay") {
+      if (c.getAttribute("id") === "annotations") {
+        for (let f = 0; f < c.childNodes.length; f++) {
+          const g = c.childNodes.item(f);
+          g && g.nodeType === 1 && (i += o.serializeToString(g));
+        }
+        continue;
+      }
+      i += o.serializeToString(c);
+    }
+  }
+  return i;
+}
+function re(e) {
+  const t = e.cloneNode(!0);
+  for (let r = t.childNodes.length - 1; r >= 0; r--) {
+    const n = t.childNodes.item(r);
+    if (!n || n.nodeType !== 1) continue;
+    const o = n;
+    (o.localName ?? o.tagName ?? "") === "style" && o.hasAttribute("data-annot-fonts") && t.removeChild(n);
+  }
+  return t.childNodes.length === 0 ? null : t;
+}
+function Pe(e = {}) {
+  const t = {
+    loadSystemFonts: e.loadSystemFonts ?? !1,
+    ...e.fontFiles ? { fontFiles: e.fontFiles } : {},
+    ...e.fontDirs ? { fontDirs: e.fontDirs } : {},
+    ...e.defaultFontFamily ? { defaultFontFamily: e.defaultFontFamily } : {}
+  };
+  function r(n) {
+    const o = $(n), s = new P(o, {
+      fitTo: { mode: "width", value: n.width },
+      background: "rgba(0, 0, 0, 0)",
+      font: t
+    }).render();
+    return {
+      pixels: s.pixels,
+      width: s.width,
+      height: s.height
+    };
+  }
+  return {
+    toSvg(n) {
+      return $(n);
+    },
+    toPng(n) {
+      const o = $(n);
+      return new P(o, {
+        fitTo: { mode: "width", value: n.width },
+        background: "rgba(0, 0, 0, 0)",
+        font: t
+      }).render().asPng();
+    },
+    async toEncoded(n, o) {
+      const { pixels: i, width: s, height: a } = r(n);
+      return O(i, s, a, o);
+    }
+  };
+}
+function $(e) {
+  const t = "http://www.w3.org/2000/svg", r = "http://www.w3.org/1999/xlink", n = te(e.annotationsSvg);
+  return `<svg xmlns="${t}" xmlns:xlink="${r}" ${M}="${W}" width="${e.width}" height="${e.height}" viewBox="0 0 ${e.width} ${e.height}"><image href="${e.originalDataUrl}" width="${e.width}" height="${e.height}"/>` + n + "</svg>";
+}
+const Be = {
+  BBox: {
+    type: "object",
+    required: ["x", "y", "width", "height"],
+    additionalProperties: !1,
+    properties: {
+      x: { type: "number" },
+      y: { type: "number" },
+      width: { type: "number", minimum: 0 },
+      height: { type: "number", minimum: 0 }
+    }
+  },
+  Point: {
+    type: "object",
+    required: ["x", "y"],
+    additionalProperties: !1,
+    properties: {
+      x: { type: "number" },
+      y: { type: "number" }
+    }
+  },
+  Intent: {
+    type: "string",
+    enum: ["info", "warning", "error", "success", "neutral"]
+  },
+  AnnotationStyle: {
+    type: "object",
+    additionalProperties: !1,
+    properties: {
+      intent: { $ref: "#/$defs/Intent" },
+      stroke: { type: "string" },
+      strokeWidth: { type: "number", minimum: 0 },
+      fill: { type: "string" },
+      color: { type: "string" }
+    }
+  }
+}, ne = {
+  type: "object",
+  required: ["type", "bbox"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "rect" },
+    bbox: { $ref: "#/$defs/BBox" },
+    intent: { $ref: "#/$defs/Intent" },
+    stroke: { type: "string" },
+    strokeWidth: { type: "number", minimum: 0 },
+    fill: { type: "string" },
+    color: { type: "string" }
+  }
+}, oe = {
+  type: "object",
+  required: ["type", "center", "radius"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "circle" },
+    center: { $ref: "#/$defs/Point" },
+    radius: { type: "number", minimum: 0 },
+    intent: { $ref: "#/$defs/Intent" },
+    stroke: { type: "string" },
+    strokeWidth: { type: "number", minimum: 0 },
+    fill: { type: "string" },
+    color: { type: "string" }
+  }
+}, ie = {
+  type: "object",
+  required: ["type", "from", "to"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "arrow" },
+    from: { $ref: "#/$defs/Point" },
+    to: { $ref: "#/$defs/Point" },
+    intent: { $ref: "#/$defs/Intent" },
+    stroke: { type: "string" },
+    strokeWidth: { type: "number", minimum: 0 },
+    color: { type: "string" }
+  }
+}, se = {
+  type: "object",
+  required: ["type", "at", "content"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "text" },
+    at: { $ref: "#/$defs/Point" },
+    content: { type: "string" },
+    fontSize: { type: "number", minimum: 0 },
+    anchor: { type: "string", enum: ["start", "middle", "end"] },
+    intent: { $ref: "#/$defs/Intent" },
+    color: { type: "string" }
+  }
+}, ae = {
+  type: "object",
+  required: ["type", "at", "targetBbox", "content"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "callout" },
+    at: { $ref: "#/$defs/Point" },
+    targetBbox: { $ref: "#/$defs/BBox" },
+    content: { type: "string" },
+    intent: { $ref: "#/$defs/Intent" },
+    stroke: { type: "string" },
+    color: { type: "string" }
+  }
+}, ce = {
+  type: "object",
+  required: ["type", "svgFragment"],
+  additionalProperties: !1,
+  properties: {
+    type: { const: "raw" },
+    svgFragment: { type: "string" }
+  }
+}, Ee = {
+  oneOf: [ne, oe, ie, se, ae, ce]
+}, _e = {
+  type: "object",
+  required: ["bbox"],
+  additionalProperties: !1,
+  properties: {
+    bbox: { $ref: "#/$defs/BBox" },
+    style: { type: "string", enum: ["solid", "mosaic", "blur"] },
+    color: { type: "string" }
+  }
+};
+function F(e, t = {}) {
+  const r = t.stroke ?? "red", n = t.strokeWidth ?? 2, o = t.fill ?? "none";
+  return `<rect x="${e.x}" y="${e.y}" width="${e.width}" height="${e.height}" fill="${p(o)}" stroke="${p(r)}" stroke-width="${n}"/>`;
+}
+function z(e, t, r = {}) {
+  const n = r.color ?? "red", o = r.strokeWidth ?? 2, i = `annot-arrow-${le()}`;
+  return `<defs><marker id="${i}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto" markerUnits="strokeWidth"><path d="M 0 0 L 10 5 L 0 10 z" fill="${p(n)}"/></marker></defs><line x1="${e.x}" y1="${e.y}" x2="${t.x}" y2="${t.y}" stroke="${p(n)}" stroke-width="${o}" marker-end="url(#${i})"/>`;
+}
+function D(e, t, r = {}) {
+  const n = r.color ?? "red", o = r.fontSize ?? 14, i = r.anchor ?? "start";
+  return `<text x="${e.x}" y="${e.y}" fill="${p(n)}" font-size="${o}" text-anchor="${i}">` + fe(t) + "</text>";
+}
+let k = 0;
+function le() {
+  return k = k + 1 | 0, k;
+}
+function p(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function fe(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const ge = {
+  info: { stroke: "#3b82f6", fill: "rgba(59, 130, 246, 0.12)", text: "#1e40af" },
+  warning: { stroke: "#f59e0b", fill: "rgba(245, 158, 11, 0.12)", text: "#92400e" },
+  error: { stroke: "#ef4444", fill: "rgba(239, 68, 68, 0.12)", text: "#991b1b" },
+  success: { stroke: "#10b981", fill: "rgba(16, 185, 129, 0.12)", text: "#065f46" },
+  neutral: { stroke: "#6b7280", fill: "rgba(107, 114, 128, 0.12)", text: "#374151" }
+}, ue = "error";
+function y(e) {
+  const t = e.intent ?? ue, r = ge[t];
+  return {
+    stroke: e.stroke ?? r.stroke,
+    fill: e.fill ?? "none",
+    text: e.color ?? r.text
+  };
+}
+function Ce(e) {
+  return e.map(de).join("");
+}
+function de(e) {
+  switch (e.type) {
+    case "rect":
+      return he(e);
+    case "circle":
+      return me(e);
+    case "arrow":
+      return pe(e);
+    case "text":
+      return ye(e);
+    case "callout":
+      return we(e);
+    case "raw":
+      return be(e);
+  }
+}
+function he(e) {
+  const t = y(e);
+  return F(e.bbox, {
+    stroke: t.stroke,
+    strokeWidth: e.strokeWidth ?? 2,
+    fill: t.fill
+  });
+}
+function me(e) {
+  const t = y(e), r = e.strokeWidth ?? 2;
+  return `<circle cx="${e.center.x}" cy="${e.center.y}" r="${e.radius}" fill="${_(t.fill)}" stroke="${_(t.stroke)}" stroke-width="${r}"/>`;
+}
+function pe(e) {
+  const t = y(e);
+  return z(e.from, e.to, {
+    color: t.stroke,
+    strokeWidth: e.strokeWidth ?? 2
+  });
+}
+function ye(e) {
+  const t = y(e);
+  return D(e.at, e.content, {
+    color: t.text,
+    fontSize: e.fontSize ?? 14,
+    anchor: e.anchor ?? "start"
+  });
+}
+function we(e) {
+  const t = y(e), r = e.targetBbox, n = xe(r, e.at);
+  return F(r, {
+    stroke: t.stroke,
+    strokeWidth: e.strokeWidth ?? 2,
+    fill: t.fill
+  }) + z(e.at, n, {
+    color: t.stroke,
+    strokeWidth: 2
+  }) + D(e.at, e.content, {
+    color: t.text,
+    fontSize: 14,
+    anchor: "start"
+  });
+}
+function be(e) {
+  return e.svgFragment;
+}
+function xe(e, t) {
+  const r = E(t.x, e.x, e.x + e.width), n = E(t.y, e.y, e.y + e.height);
+  return { x: r, y: n };
+}
+function E(e, t, r) {
+  return Math.min(Math.max(e, t), r);
+}
+function _(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+export {
+  Ee as BBOX_ANNOTATION_SCHEMA,
+  _e as BBOX_REDACT_REGION_SCHEMA,
+  C as DEFAULT_ENCODE_OPTIONS,
+  Se as SAVE_SIZE_LABEL,
+  X as SAVE_SIZE_MAX_WIDTH,
+  Be as SHARED_DEFS,
+  z as arrowBetween,
+  Ce as bboxAnnotationsToSvg,
+  V as computeResizeTarget,
+  Pe as createAnnotator,
+  Te as decodeAndEncodeImage,
+  O as encodeRgba,
+  ve as isImagequantAvailable,
+  K as isPhotoHeavy,
+  F as rectForBoundingBox,
+  D as textAt
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-annotator",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Headless annotator — render annotated screenshots from Node without a browser. Built on @resvg/resvg-js. Pairs with @ingcreators/annot-playwright for fail-on-test annotated reports.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -44,13 +44,16 @@
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vite": "^8.0.13",
+    "vite": "^6.4.2",
     "vite-plugin-dts": "^5.0.0",
     "@ingcreators/annot-core": "0.1.0"
   },
   "dependencies": {
+    "@napi-rs/canvas": "^0.1.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@xmldom/xmldom": "^0.9.10"
+    "@xmldom/xmldom": "^0.9.10",
+    "pako": "^2.1.0",
+    "@ingcreators/annot-imagequant": "0.1.0"
   },
   "scripts": {
     "build": "vite build",