@ingcreators/annot-annotator 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # @ingcreators/annot-annotator
 
+## 0.5.0
+
+### Minor Changes
+
+- 806badc: Retire the `@ingcreators/annot-imagequant` (GPL-3.0) dynamic-import
+  boundary that gated PNG-8 output in the headless annotator and the
+  MCP server. `Annotator.toEncoded()`'s smart mode now routes PNG-8
+  through the pure-TS Median Cut + Floyd–Steinberg dither at
+  `@ingcreators/annot-core/encode/quantize-median-cut` directly.
+
+  ### Removed public API
+  - `isImagequantAvailable()` is no longer exported from
+    `@ingcreators/annot-annotator`. PNG-8 is now unconditionally
+    available — callers that previously gated `format: "smart"` on
+    this can drop the check.
+  - `Annotator.toEncoded()` no longer emits
+    `EncodeResult.reason === "imagequant-missing"`. The
+    graceful-PNG-32-fallback path that produced this reason is
+    unreachable.
+
+  ### Removed dependency
+  - `@ingcreators/annot-imagequant` is dropped from
+    `@ingcreators/annot-annotator`'s `dependencies`. Consumers
+    that previously installed it as a side-effect of installing
+    `annot-annotator` will save the WASM payload from their
+    `node_modules`. `annot-mcp` inherits the removal transitively.
+
+  Phase 3 of `docs/plans/replace-libimagequant-with-median-cut.md`.
+  Phase 4 deletes the `@ingcreators/annot-imagequant` workspace
+  package and deprecates the published 0.1.0 on npm.
+
+- df1a429: **`@ingcreators/annot-annotator` — new `Annotator.toEditablePng()`
+  method** that returns a re-editable PNG. The bytes carry the same
+  visible pixels as `toPng()` plus the original un-annotated capture +
+  the annotations SVG embedded in the PNG's XMP / custom `svGo` chunk.
+  Re-opening the file in the Annot editor (or `annot.work/app/`)
+  restores the annotations as selectable / movable / restylable
+  objects rather than a flat bitmap.
+
+  ```ts
+  const annotator = createAnnotator();
+  const editablePng = annotator.toEditablePng({
+    originalDataUrl,
+    annotationsSvg,
+    width,
+    height,
+    tags: {
+      source: "playwright-fixture",
+      capturedAt: new Date().toISOString(),
+    },
+  });
+  await writeFile("shot.png", editablePng);
+  ```
+
+  Image viewers that don't know about the custom chunks display the
+  rasterised pixels verbatim — no compatibility loss vs `toPng()`.
+
+  The existing `toPng()` / `toSvg()` / `toEncoded()` methods are
+  unchanged — `toEditablePng()` is purely additive.
+
+  **`@ingcreators/annot-core` — new `/xmp-bytes` Tier-A subpath**
+  exposing the pure-bytes XMP encode / decode primitives that used to
+  live (Blob-wrapped) inside `/xmp`:
+  - `createEditablePngBytes(opts) -> Uint8Array` — write a re-editable
+    PNG. Takes raw PNG bytes for both the rasterised image and the
+    original capture; no `Blob` / `FileReader` dependency. The
+    function the new `Annotator.toEditablePng()` is built on.
+  - `readEditablePngBytes(data) -> AnnotMetadata | null` — PNG-only
+    reader.
+  - `readEditableImage(data) -> AnnotMetadata | null` — dual PNG /
+    JPEG reader (moved here from `/xmp`, also re-exported from `/xmp`
+    for source-compat).
+  - `WELL_KNOWN_TAG_KEYS` — soft-convention key names for the
+    optional `tags` field (`source` / `screen` / `capturedAt` /
+    `commit`).
+
+  Existing `@ingcreators/annot-core/xmp` consumers stay working
+  without source changes — `xmp-browser.ts` re-exports the Tier-A
+  surface alongside its Blob-wrapped `createEditableImage`.
+
+## 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

package/README.md

@@ -129,7 +129,7 @@ See also:
 - [`docs/plans/_done/headless-annotator-spike.md`](../../docs/plans/_done/headless-annotator-spike.md)
   — Phase 0 feasibility report (`@resvg/resvg-js` vs
   `@napi-rs/canvas` trade-offs; documented gaps).
-- [`docs/plans/annot-annotator-package.md`](../../docs/plans/annot-annotator-package.md)
+- [`docs/plans/_done/annot-annotator-package.md`](../../docs/plans/_done/annot-annotator-package.md)
   — Phase 1 design + rationale for the public API shape.
 - [`PRODUCT_DIRECTION.md`](../../PRODUCT_DIRECTION.md) — strategic
   context (Playwright + GitHub vectors).

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
@@ -18,6 +20,22 @@ export interface AnnotatorInput {
     /** Output PNG height in pixels — should match the source bitmap. */
     height: number;
 }
+/**
+ * Input for {@link Annotator.toEditablePng}. Same shape as
+ * {@link AnnotatorInput} plus optional opaque kv `tags` written into
+ * the embedded XMP for provenance / debugging.
+ *
+ * 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.
+ */
+export interface EditableInput extends AnnotatorInput {
+    /** Optional opaque kv tags. */
+    tags?: Record<string, string>;
+}
 /** Annotator construction options. All optional. */
 export interface AnnotatorOptions {
     /**
@@ -47,16 +65,27 @@ 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 in-tree
+ *                     pure-TS Median Cut + Floyd–Steinberg dither
+ *                     (post-Phase 3 of
+ *                     `docs/plans/_done/replace-libimagequant-with-median-cut.md`;
+ *                     prior versions used the GPL-3.0
+ *                     `@ingcreators/annot-imagequant` WASM).
  */
 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 +94,37 @@ export interface Annotator {
      * the caller can feed to any other SVG tool.
      */
     toSvg(input: AnnotatorInput): string;
+    /**
+     * Rasterise the input to a re-editable PNG. Same visible pixels as
+     * {@link toPng}, plus the original un-annotated capture + the
+     * annotations SVG are embedded in the PNG's XMP metadata + custom
+     * `svGo` chunk. Re-opening the resulting file in the Annot editor
+     * (or `annot.work/app/`) restores the annotations as selectable,
+     * movable, restylable objects rather than a flat bitmap.
+     *
+     * Image viewers that don't know about the custom chunks display the
+     * rasterised pixels verbatim — no compatibility loss vs `toPng`.
+     *
+     * Synchronous. Returns PNG bytes as a `Uint8Array`.
+     */
+    toEditablePng(input: EditableInput): Uint8Array;
+    /**
+     * 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 emits PNG-8 (via the in-tree Median Cut +
+     * Floyd–Steinberg dither at
+     * `@ingcreators/annot-core/encode/quantize-median-cut`) for
+     * UI-heavy content, falling back to PNG-32 / JPEG for
+     * photo-heavy content per `smartFallback`. PNG-8 is
+     * unconditionally available since Phase 3 of
+     * `docs/plans/_done/replace-libimagequant-with-median-cut.md`
+     * retired the optional GPL-3.0 imagequant WASM dependency.
+     */
+    toEncoded(input: AnnotatorInput, encodeOptions?: EncodeOptions): Promise<EncodeResult>;
 }
 /**
  * Construct a headless annotator. Options are forwarded to the

package/dist/dsl/types.d.ts

@@ -52,11 +52,53 @@ export type BboxCalloutAnnotation = AnnotationStyle & {
     targetBbox: BBox;
     content: string;
 };
+/**
+ * Which corner of the target bbox the badge sits at. The badge
+ * is centred on the corner — half inside the rect, half outside —
+ * so the legend number remains readable against either light or
+ * dark target content. `"auto"` (the default) picks the corner
+ * that's furthest from the supplied image edge so the badge
+ * never clips off the screenshot.
+ */
+export type BadgePlacement = "auto" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+/**
+ * Numbered legend badge — target rect outline plus a filled
+ * intent-coloured circle at one corner with a bold white number
+ * inside. The visual idiom for "this is item N in a step-by-step
+ * legend over a screenshot."
+ *
+ * Differs from `callout` in two ways:
+ * 1. No caption arrow — the badge sits ON the target, not next to it.
+ * 2. The number renders inside a sized circle, not as bare `<text>`,
+ *    so it stays readable when the screenshot is scaled down in
+ *    docs / slides.
+ *
+ * When `imageWidth` / `imageHeight` are supplied alongside
+ * `placement: "auto"`, the renderer picks the corner furthest
+ * from the image edge so the badge never clips. Without those,
+ * `"auto"` falls back to `"topRight"`.
+ */
+export type BboxNumberedBadgeAnnotation = AnnotationStyle & {
+    type: "numberedBadge";
+    bbox: BBox;
+    number: number;
+    /** Override the corner. Default `"auto"`. */
+    placement?: BadgePlacement;
+    /** Badge diameter in image pixels. Default `40`. */
+    badgeSize?: number;
+    /**
+     * Image dimensions in page pixels — used by `placement: "auto"`
+     * to pick the corner furthest from the image edge. When omitted,
+     * `"auto"` resolves to `"topRight"`.
+     */
+    imageWidth?: number;
+    imageHeight?: number;
+};
 export interface RawAnnotation {
     type: "raw";
     svgFragment: string;
 }
-export type BboxAnnotation = BboxRectAnnotation | BboxCircleAnnotation | BboxArrowAnnotation | BboxTextAnnotation | BboxCalloutAnnotation | RawAnnotation;
+export type BboxAnnotation = BboxRectAnnotation | BboxCircleAnnotation | BboxArrowAnnotation | BboxTextAnnotation | BboxCalloutAnnotation | BboxNumberedBadgeAnnotation | RawAnnotation;
 export type RedactStyle = "solid" | "mosaic" | "blur";
 export interface BboxRedactRegion {
     bbox: BBox;

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 the
+ *              in-tree Median Cut + FS dither and emit PNG-8 with
+ *              reason `"png-8"`. PNG-8 is unconditionally
+ *              available post-Phase 3 (no optional WASM gate).
+ */
+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,17 @@
+/**
+ * Quantize RGBA pixels to ≤256 colours via Median Cut + Floyd–
+ * Steinberg dither and emit a PNG-8 file.
+ *
+ * Synchronous, deterministic, GPL-free.
+ */
+export declare function quantizeRgbaToPng8(rgba: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * 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;

package/dist/index.d.ts

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