@ingcreators/annot-annotator 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @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

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

@@ -20,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 {
     /**
@@ -57,8 +73,12 @@ export interface AnnotatorOptions {
  * - {@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`.
+ *                     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 {
     /**
@@ -74,6 +94,20 @@ 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"` /
@@ -81,12 +115,14 @@ export interface Annotator {
      * 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"`.
+     * 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>;
 }

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

@@ -16,10 +16,10 @@ import { EncodeResult } from './options.js';
  *            - 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"`.
+ *            - 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>;
 /**

package/dist/encode/quantize.d.ts

@@ -1,12 +1,10 @@
 /**
- * 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.
+ * Quantize RGBA pixels to ≤256 colours via Median Cut + Floyd–
+ * Steinberg dither and emit a PNG-8 file.
  *
- * The caller is responsible for falling back to a non-PNG-8 path
- * (PNG-32 or JPEG) when this returns `null`.
+ * Synchronous, deterministic, GPL-free.
  */
-export declare function quantizeRgbaToPng8(rgba: Uint8Array, width: number, height: number): Promise<Uint8Array | null>;
+export declare function quantizeRgbaToPng8(rgba: Uint8Array, width: number, height: number): Uint8Array;
 /**
  * Heuristic: does this image look photo-heavy?
  *
@@ -17,7 +15,3 @@ export declare function quantizeRgbaToPng8(rgba: Uint8Array, width: number, heig
  * 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,8 +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 { isImagequantAvailable, isPhotoHeavy } from './encode/quantize.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';