@ingcreators/annot-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @ingcreators/annot-core
 
+## 0.2.0
+
+### Minor Changes
+
+- 2e8d397: Switch the client-capture PNG-8 default quantizer to the pure-TS
+  Median Cut at `@ingcreators/annot-core/encode/quantize-median-cut`.
+  `DEFAULT_ENCODE_OPTIONS.quantizer` is now `"median-cut"`. The
+  `@ingcreators/annot-imagequant` WASM import and the `ensureWasm()`
+  initialisation path are removed from `@ingcreators/annot-core/encode`.
+  The `quantizer: "wasm"` value on `EncodeOptions` is retained for
+  back-compat (now resolves to the same Median Cut implementation)
+  so consumers that persisted `quantizer: "wasm"` to localStorage
+  keep working unchanged.
+
+  Phase 2 of `docs/plans/replace-libimagequant-with-median-cut.md`.
+  Phase 3 retires the annotator / MCP dynamic-import path; Phase 4
+  deletes the workspace package and deprecates the published
+  `@ingcreators/annot-imagequant@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`.
+
+- 5e74421: Add `quantizeMedianCut` — a pure-TS Median Cut + Floyd–Steinberg
+  dither quantizer at `@ingcreators/annot-core/encode/quantize-median-cut`
+  — and an opt-in `quantizer?: "wasm" | "median-cut"` field on
+  `EncodeOptions`. Default stays `"wasm"` (libimagequant via the
+  existing GPL-3.0 WASM dependency) so production behaviour is
+  unchanged. Phase 1 of
+  `docs/plans/replace-libimagequant-with-median-cut.md`; Phase 2
+  will flip the default to `"median-cut"` and Phase 4 will retire
+  the `"wasm"` branch entirely.
+- 4768855: **`@ingcreators/annot-product-docs-astro` — new `/playwright`
+  subpath** that re-exports an extended Playwright `test` fixture
+  whose `page.screenshot()` accepts a compositional `annot: { … }`
+  option:
+
+  ```ts
+  import { test } from "@ingcreators/annot-product-docs-astro/playwright";
+
+  test("login flow", async ({ page }) => {
+    await page.goto("/login");
+    await page.screenshot({
+      path: "public/login.png",
+      annot: {
+        mdx: { id: "login", path: "src/content/docs/login.mdx" },
+        tags: { source: "docs-tour", capturedAt: new Date().toISOString() },
+      },
+    });
+  });
+  ```
+
+  The `annot` option is compositional — each field is an
+  independent contribution to the embedded XMP record:
+  - `mdx: { id, path }` — refresh the MDX's `annot:snapshot` block
+    against the current page, then resolve `<Overlay match>` blocks
+    for the named `<Screen>`.
+  - `overlays: BboxAnnotation[]` — caller-supplied annotations
+    (same DSL `@ingcreators/annot-annotator` accepts). Merged with
+    MDX-derived overlays when both are present.
+  - `tags: Record<string, string>` — provenance metadata written
+    verbatim into the XMP. No auto-fill — callers write the
+    `WELL_KNOWN_TAG_KEYS` they want.
+  - `editable: boolean` (default `true`) — toggle between
+    "annotations preserved as SVG layer + embedded original"
+    (re-editable in Annot Cloud) and "annotations baked into
+    visible pixels" (flat PNG, no XMP layer).
+
+  `page.screenshot()` calls WITHOUT `annot` fall through to
+  vanilla Playwright byte-for-byte — codegen / DevTools Recorder
+  output keeps working unedited.
+
+  Phase 1 of
+  `docs/plans/playwright-screenshot-annot-fixture.md`. Phase 2 will
+  add the same interception on `locator.screenshot()` with
+  coordinate rebasing for sub-region overlays.
+
+  Two helpers also exported from the main `@ingcreators/annot-product-docs-astro`
+  entry for callers who want to compose annotations themselves:
+  - `resolveMdxAnnotations({ mdxPath, screenId, dims })` — extract
+    the MDX's `<Overlay>` blocks into a typed `BboxNumberedBadgeAnnotation[]`
+    (the underlying step the fixture uses internally).
+  - `svgFromBboxAnnotations(annotations)` — wrap a
+    `BboxAnnotation[]` into a single-root `<svg>` ready for
+    `Annotator.toEditablePng()` / `toPng()`.
+
+  **`@ingcreators/annot-core` — new `writePngWithTagsOnly`
+  helper** exported from `/xmp-bytes` (and re-exported from
+  `/xmp`). Writes `tags` into a PNG's XMP iTXt chunk without
+  embedding an original capture or annotations layer — for the
+  "PNG with provenance metadata sidecar" path (CI failure
+  screenshots, VRT references, etc.). The resulting bytes are
+  still a valid PNG and the Annot editor treats them as a normal
+  PNG (no `<annot:annotations>` element → not editable round-trip;
+  opens as fresh canvas).
+
+### Patch Changes
+
+- 780985d: Remove the `@ingcreators/annot-imagequant` workspace dependency
+  graph entirely. The package's GPL-3.0 WASM was replaced by the
+  pure-TS Median Cut quantizer in Phases 1–3 of
+  `docs/plans/_done/replace-libimagequant-with-median-cut.md`;
+  Phase 4 deletes the workspace package itself + the `verify-wasm`
+  CI job + the Cargo dependabot watch + the issue-template option +
+  the published 0.1.0 on npm (via the `npm deprecate` operator
+  action documented in the Phase 4 PR description).
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,8 @@
 # @ingcreators/annot-core
 
+[![npm](https://img.shields.io/npm/v/@ingcreators/annot-core.svg)](https://www.npmjs.com/package/@ingcreators/annot-core)
+[![license](https://img.shields.io/npm/l/@ingcreators/annot-core.svg)](https://github.com/ingcreators/annot/blob/main/LICENSE)
+
 The shared core of [Annot](../../README.md). Two tiers live here:
 
 - **Tier A** — pure Node, DOM-free. Storage types, SVG format
@@ -16,19 +19,40 @@ PropertyPanel, tools) live in [`@ingcreators/annot-editor`](../editor).
 Data-driven canvas rendering (gallery thumbnails, the shared OOXML
 DrawingML builder) lives in [`@ingcreators/annot-render`](../render).
 
+## Install (npm)
+
+```sh
+npm install @ingcreators/annot-core
+# or
+pnpm add @ingcreators/annot-core
+```
+
+Most consumers will install the higher-level
+[`@ingcreators/annot-annotator`](https://www.npmjs.com/package/@ingcreators/annot-annotator)
+or [`@ingcreators/annot-playwright`](https://www.npmjs.com/package/@ingcreators/annot-playwright)
+instead — those packages inline the parts of `annot-core` they
+need. Install `annot-core` directly only when building a custom
+headless tool against the SDK.
+
 ## Public entry points
 
-| Subpath | Tier | Surface |
-|---------|------|---------|
-| `@ingcreators/annot-core` | A | Re-exports everything from `/headless` — DOM-free root entry |
-| `@ingcreators/annot-core/headless` | A | Same as root, kept as an alias for callers that want to be explicit |
-| `@ingcreators/annot-core/storage` | A | `ImageRecord`, `FolderRecord`, `PageElement`, `PageMetadata`, `StorageProvider` |
-| `@ingcreators/annot-core/utils` | A | `assertNonNull`, `computeDasharray`, `newIdB58`, defaults |
-| `@ingcreators/annot-core/zip` | A | ZIP builder used by PPTX export |
-| `@ingcreators/annot-core/encode` | A | Image encode helpers |
-| `@ingcreators/annot-core/editor` | B | jsdom-friendly element helpers + `TOOL_REGISTRY` / `PROPERTY_CONTROLS` |
-| `@ingcreators/annot-core/xmp` | browser | `createEditableImage` / `readEditableImage` round-trip |
-| `@ingcreators/annot-core/desktop-bridge` | browser | Electron desktop-host IPC + `isDesktop` detection |
+| Subpath | Tier | Surface | Available on npm? |
+|---------|------|---------|---|
+| `@ingcreators/annot-core` | A | Re-exports everything from `/headless` — DOM-free root entry | ✅ |
+| `@ingcreators/annot-core/headless` | A | Same as root, kept as an alias for callers that want to be explicit | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/storage` | A | `ImageRecord`, `FolderRecord`, `PageElement`, `PageMetadata`, `StorageProvider` | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/utils` | A | `assertNonNull`, `computeDasharray`, `newIdB58`, defaults | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/zip` | A | ZIP builder used by PPTX export | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/encode` | A | Image encode helpers | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/editor` | B | jsdom-friendly element helpers + `TOOL_REGISTRY` / `PROPERTY_CONTROLS` | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/xmp` | browser | `createEditableImage` / `readEditableImage` round-trip | workspace only (v0.1.0) |
+| `@ingcreators/annot-core/desktop-bridge` | browser | Electron desktop-host IPC + `isDesktop` detection | workspace only (v0.1.0) |
+
+Subpath imports for npm consumers land in a later minor — the
+v0.1.0 published tarball bundles everything into the root
+`./dist/index.js` entry. Workspace consumers (within this
+monorepo) keep using the full subpath map via the source-side
+exports.
 
 The Tier A surface is CI-enforced by
 [`src/headless.test.ts`](./src/headless.test.ts): it imports every

package/dist/encode/options.d.ts

@@ -1,9 +1,9 @@
 /**
- * Encode option types + defaults — split out of `./index.ts` so callers
- * that only need the data shape (e.g. the web app's preferences
- * loader) can import this leaf without dragging in the WASM
- * imagequant binding that `encodeCapture` requires. Keeps the
- * encoder lazy-loadable as a separate chunk.
+ * Encode option types + defaults — split out of `./index.ts` so
+ * callers that only need the data shape (e.g. the web app's
+ * preferences loader) can import this leaf without dragging in
+ * the heavier encoder + quantizer module that `encodeCapture`
+ * requires. Keeps the encoder lazy-loadable as a separate chunk.
  */
 export type EncodeFormat = "smart" | "png" | "jpeg";
 /**
@@ -23,6 +23,23 @@ export declare const SAVE_SIZE_MAX_WIDTH: Record<SaveSizePreset, number | null>;
  *  + the (future) extension settings UI. Shared so both surfaces
  *  speak the same language. */
 export declare const SAVE_SIZE_LABEL: Record<SaveSizePreset, string>;
+/**
+ * Quantizer backend for PNG-8 smart-mode encoding.
+ *
+ * Both values currently resolve to the in-tree pure-TS Median Cut
+ * + Floyd–Steinberg dither at
+ * [`quantize-median-cut.ts`](./quantize-median-cut.ts). The
+ * `"wasm"` value is retained for back-compat with the Phase 1
+ * feature flag so consumers that persisted `quantizer: "wasm"` to
+ * localStorage keep working unchanged.
+ *
+ * Phase 2 of
+ * [`docs/plans/_done/replace-libimagequant-with-median-cut.md`](../../../../docs/plans/_done/replace-libimagequant-with-median-cut.md)
+ * flipped the default to Median Cut and removed the WASM init
+ * path. Phase 4 deletes the `@ingcreators/annot-imagequant`
+ * workspace package and removes this field entirely.
+ */
+export type Quantizer = "wasm" | "median-cut";
 export interface EncodeOptions {
     /** "smart" | "png" | "jpeg" */
     format: EncodeFormat;
@@ -53,6 +70,12 @@ export interface EncodeOptions {
      * `Settings.quality.saveSizePreset` field here.
      */
     saveSizePreset?: SaveSizePreset;
+    /**
+     * Quantizer backend used by smart-mode PNG-8 output. Optional;
+     * both values resolve to the same Median Cut implementation
+     * post-Phase 2. See {@link Quantizer}.
+     */
+    quantizer?: Quantizer;
 }
 export declare const DEFAULT_ENCODE_OPTIONS: EncodeOptions;
 /** Compute the resize target for a given source size + preset.

package/dist/encode/quantize-median-cut.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure-TS palette quantizer (Median Cut + Floyd–Steinberg dither).
+ *
+ * Drop-in replacement for the WASM `quantize_image` from the
+ * (GPL-3.0) `@ingcreators/annot-imagequant` package. Lives at
+ * Tier A — no DOM, no canvas, no WASM. Importable from Node and
+ * the browser identically.
+ *
+ * The API mirrors the existing internal contract so callers can
+ * swap one for the other without touching anything else:
+ *
+ * ```ts
+ * const { palette, indices } = quantizeMedianCut(rgba, w, h, 256);
+ * ```
+ *
+ * - `palette`: flat RGBA8 bytes, length `numColors * 4`.
+ * - `indices`: one byte per pixel, length `w * h`.
+ *
+ * Deterministic: same input always produces the same output.
+ * Priority-queue ties are broken by insertion order; splits use
+ * a stable sort. Useful for snapshot tests.
+ *
+ * Algorithm summary:
+ *
+ * 1. Build a histogram (Map<rgba32, count>) over the input.
+ * 2. Split samples below an alpha threshold into a dedicated
+ *    "transparent" palette entry (index 0).
+ * 3. Place the remaining samples into a single bounding box and
+ *    repeatedly split the highest-priority box along its longest
+ *    RGB edge at the population-weighted median, until the
+ *    target palette size is reached.
+ * 4. Each box contributes one palette entry — the population-
+ *    weighted mean of its samples.
+ * 5. Remap the source image to palette indices with
+ *    Floyd–Steinberg error diffusion in scanline order.
+ *
+ * @see `quantize-median-cut.test.ts` for the property tests.
+ */
+export interface QuantizeResult {
+    /** Flat RGBA8 palette bytes, length = numColors * 4 (1 ≤ N ≤ 256). */
+    palette: Uint8Array;
+    /** One byte per pixel, indexing into the palette. */
+    indices: Uint8Array;
+}
+/**
+ * Quantize an RGBA image to ≤ `maxColors` palette entries.
+ *
+ * @param rgba   Packed RGBA8 input, length must equal `width*height*4`.
+ * @param width  Image width in pixels (≥ 1).
+ * @param height Image height in pixels (≥ 1).
+ * @param maxColors Target palette size, clamped to [1, 256].
+ */
+export declare function quantizeMedianCut(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number, maxColors: number): QuantizeResult;

package/dist/index.js

@@ -502,14 +502,12 @@ function de(e, t, n, r, i, a, o) {
 	};
 	n.x += -s * 2, n.y += -c * 2, e.moveTo(d.x - l - u / t, d.y - u + l / t), e.lineTo(d.x, d.y), e.lineTo(d.x + u / t - l, d.y - u - l / t);
 }
-function fe(e, t, n, r, i, a, o) {
-	let s = t ? .9862 : Math.SQRT1_2, c = r * o * s, l = i * o * s, u = r * (a + o), d = i * (a + o), f = {
-		x: n.x - c,
-		y: n.y - l
+function fe(e, t, n, r, i, a) {
+	let o = n * a * Math.SQRT1_2, s = r * a * Math.SQRT1_2, c = n * (i + a), l = r * (i + a), u = {
+		x: t.x - o,
+		y: t.y - s
 	};
-	n.x += -u - c, n.y += -d - l;
-	let p = t ? 3.4 : 2;
-	e.moveTo(f.x, f.y), e.lineTo(f.x - u / 2 - d / p, f.y + u / p - d / 2), e.lineTo(f.x - u, f.y - d), e.lineTo(f.x - u / 2 + d / p, f.y - d / 2 - u / p), e.close();
+	t.x += -c - o, t.y += -l - s, e.moveTo(u.x, u.y), e.lineTo(u.x - c / 2 - l / 2, u.y + c / 2 - l / 2), e.lineTo(u.x - c, u.y - l), e.lineTo(u.x - c / 2 + l / 2, u.y - l / 2 - c / 2), e.close();
 }
 function pe(e, t, n, r, i) {
 	let a = i / 2, o = {
@@ -542,7 +540,7 @@ function ve(e, t, n, r, i, a) {
 		case "triangle": return ue(e, s, !1, n, r, i, o, a), { filled: !0 };
 		case "stealth": return ue(e, s, !0, n, r, i, o, a), { filled: !0 };
 		case "arrow": return de(e, s, n, r, i, o, a), { filled: !1 };
-		case "diamond": return fe(e, !1, n, r, i, o, a), { filled: !0 };
+		case "diamond": return fe(e, n, r, i, o, a), { filled: !0 };
 		case "oval": return pe(e, n, r, i, o), { filled: !0 };
 	}
 	return { filled: !1 };

package/dist/xmp/xmp-browser.d.ts

@@ -1,10 +1,20 @@
 /**
  * Browser-side XMP metadata embedding for re-editable images.
- * Mirrors the Rust implementation in src-tauri/src/commands/xmp.rs
  *
- * JPEG: XMP in APP1 segment, original image in multiple APP2 segments
- * PNG:  XMP in iTXt chunk, original image in custom "svGo" chunk
+ * Wraps the Tier-A `xmp-bytes` primitives with Blob input / Blob output
+ * and adds the JPEG output path, which needs an Image + <canvas> pipeline
+ * to transcode the rendered PNG to JPEG.
+ *
+ * For Node / non-browser callers, import the Tier-A primitives
+ * directly:
+ *
+ *     import { createEditablePngBytes, readEditableImage }
+ *       from "@ingcreators/annot-core/xmp-bytes";
+ *
+ * Re-exports of Tier-A symbols below keep existing
+ * `@ingcreators/annot-core/xmp` consumers working unchanged.
  */
+export { type AnnotMetadata, type CreateEditablePngBytesOptions, createEditablePngBytes, readEditableImage, readEditablePngBytes, WELL_KNOWN_TAG_KEYS, writePngWithTagsOnly, } from './xmp-bytes.js';
 export interface EditableImageOptions {
     /** Rendered image (screenshot + annotations) as Blob */
     renderedBlob: Blob;
@@ -25,15 +35,3 @@ export interface EditableImageOptions {
  * Returns a Blob ready for download.
  */
 export declare function createEditableImage(opts: EditableImageOptions): Promise<Blob>;
-export interface AnnotMetadata {
-    originalImageDataUrl: string;
-    annotationsSvg: string;
-    width: number;
-    height: number;
-    tags: Record<string, string>;
-}
-/**
- * Read XMP metadata from a re-editable image file (JPEG or PNG).
- * Pass the file as an ArrayBuffer or Uint8Array.
- */
-export declare function readEditableImage(data: Uint8Array): AnnotMetadata | null;

package/dist/xmp/xmp-bytes.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Tier-A XMP metadata embedding for re-editable images — pure-bytes
+ * primitives that run in Node and the browser alike.
+ *
+ * This file holds the byte-level XMP build / read / write logic that
+ * used to live inside `xmp-browser.ts`. The browser-side
+ * `createEditableImage` (Blob in → Blob out) is now a thin wrapper
+ * around `createEditablePngBytes` for the PNG path.
+ *
+ * JPEG WRITE remains browser-only because the rendered PNG → JPEG
+ * conversion needs an Image + <canvas> pipeline. The JPEG READ path
+ * is pure bytes and lives here.
+ *
+ * PNG: XMP in iTXt chunk, original image in a custom "svGo" chunk.
+ * JPEG: XMP in APP1 segment, original image in one or more APP2
+ *       segments (each prefixed with `annot:OriginalImage\0`).
+ */
+export declare function buildXmp(annotationsSvg: string, width: number, height: number, tags?: Record<string, string>): string;
+export declare function dataUrlToUint8Array(dataUrl: string): Uint8Array;
+export declare function writeJpegWithMetadata(jpegData: Uint8Array, xmpBytes: Uint8Array, originalData: Uint8Array): Uint8Array;
+export declare function writePngWithMetadata(pngData: Uint8Array, xmpBytes: Uint8Array, originalData: Uint8Array): Uint8Array;
+/**
+ * Build a tags-only XMP packet — `<annot:tags>` element present,
+ * `<annot:annotations>` / `<annot:width>` / `<annot:height>` absent.
+ *
+ * Used for the "PNG with provenance metadata sidecar" path: image viewers
+ * see a normal PNG, the Annot editor reads no `<annot:annotations>` and
+ * treats it as an ordinary file, but XMP-aware tools (or this library's
+ * own reader) can extract the `tags` for downstream consumption.
+ */
+export declare function buildXmpTagsOnly(tags: Record<string, string>): string;
+/**
+ * Write `tags` into a PNG's XMP iTXt chunk without embedding an original
+ * capture or annotations layer. The resulting bytes are still a valid PNG
+ * (image viewers display the rasterised pixels) and the Annot editor
+ * treats it as a normal PNG (no `<annot:annotations>` → not editable
+ * round-trip).
+ *
+ * Use this for "I want my CI failure screenshot to carry test-id /
+ * commit metadata" style provenance sidecars.
+ *
+ * Returns the input bytes unchanged if `tags` is empty.
+ */
+export declare function writePngWithTagsOnly(pngData: Uint8Array, tags: Record<string, string>): Uint8Array;
+/**
+ * Common tag keys written by built-in Annot producers. **Not validated**
+ * at write time — `createEditablePngBytes` accepts any string/string
+ * pair. Documented as a soft convention so that downstream readers can
+ * key off the same names when present.
+ *
+ * - `source`     — what produced the PNG (e.g. `"docs-tour"`,
+ *                  `"playwright-fixture"`, `"annot-mcp"`).
+ * - `screen`     — for living-product-docs, the `<Screen id>` value.
+ * - `capturedAt` — ISO timestamp.
+ * - `commit`     — git SHA when applicable.
+ */
+export declare const WELL_KNOWN_TAG_KEYS: readonly ["source", "screen", "capturedAt", "commit"];
+export interface CreateEditablePngBytesOptions {
+    /** Rasterised PNG bytes — the visible image, with annotations already
+     *  baked into the pixels. */
+    renderedPng: Uint8Array;
+    /** Original un-annotated capture. Pass either the raw PNG/JPEG bytes
+     *  or a `data:` URL string. */
+    originalImage: Uint8Array | string;
+    /** Annotations-only SVG fragment (no `<svg>` wrapper required — this
+     *  is what the editor's `readEditableImage` will reconstruct from). */
+    annotationsSvg: string;
+    /** Image width in pixels. Written into the XMP `<annot:width>` field. */
+    width: number;
+    /** Image height in pixels. Written into the XMP `<annot:height>` field. */
+    height: number;
+    /** Optional opaque kv tags. See {@link WELL_KNOWN_TAG_KEYS} for the
+     *  soft convention. */
+    tags?: Record<string, string>;
+}
+/**
+ * Write a re-editable PNG: takes a rasterised PNG (visible image) and
+ * embeds the original capture + annotations SVG in the XMP / custom
+ * chunks. The Annot editor reads the metadata back via
+ * {@link readEditablePngBytes} / {@link readEditableImage} and
+ * reconstructs an editable document.
+ *
+ * The returned bytes are still a valid PNG — image viewers that don't
+ * know about the custom chunks display the rasterised pixels verbatim.
+ */
+export declare function createEditablePngBytes(opts: CreateEditablePngBytesOptions): Uint8Array;
+/** Parsed XMP metadata extracted from a re-editable image. */
+export interface AnnotMetadata {
+    /** Original un-annotated capture re-emitted as a `data:` URL. Empty
+     *  string when no original was embedded. MIME is inferred from the
+     *  embedded bytes' magic header (PNG vs JPEG). */
+    originalImageDataUrl: string;
+    /** Annotations-only SVG fragment recovered from the XMP. */
+    annotationsSvg: string;
+    /** Image width in pixels. */
+    width: number;
+    /** Image height in pixels. */
+    height: number;
+    /** Opaque kv tags. Empty object when the XMP carried no `<annot:tags>`
+     *  element or the embedded JSON was malformed. */
+    tags: Record<string, string>;
+}
+/**
+ * Read XMP metadata from a re-editable PNG.
+ *
+ * Returns `null` when the bytes aren't a PNG, when the PNG carries no
+ * Annot iTXt chunk, or when the XMP is missing the required
+ * `<annot:annotations>` field. For format-agnostic reading (PNG OR
+ * JPEG), use {@link readEditableImage}.
+ */
+export declare function readEditablePngBytes(data: Uint8Array): AnnotMetadata | null;
+/**
+ * Read XMP metadata from a re-editable image — PNG or JPEG. Returns
+ * `null` for any other format, for files without the Annot custom
+ * metadata, and for files whose XMP is missing the required
+ * `<annot:annotations>` field.
+ */
+export declare function readEditableImage(data: Uint8Array): AnnotMetadata | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Annot SDK — SVG-first screenshot annotation format, storage abstractions, and editor primitives. The foundation shared by the PWA, Chrome extension, Electron desktop, VSCode extension, and the headless annotator.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -45,14 +45,14 @@
     "@types/pako": "^2.0.4",
     "typescript": "^6.0.3",
     "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.0",
-    "@ingcreators/annot-imagequant": "0.1.0"
+    "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
     "pako": "^2.1.0"
   },
   "scripts": {
     "build": "vite build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "bench:quantize": "node --experimental-strip-types --no-warnings scripts/bench-quantize.ts"
   }
 }

package/styles/editor.css

@@ -140,6 +140,14 @@ body {
     0 10px,
     10px -10px,
     -10px 0;
+  /* Hidden by default — only the image editor mounts here. Gallery,
+   * doc, split-editor, and capture workspaces each own their own
+   * surface. Without this default, the checkered canvas backdrop
+   * paints on every boot before JS decides the route, producing a
+   * brief "empty editor" flash on gallery loads (e.g. `/app`, `/`,
+   * `/folder/...`). `body.editor-mode` below restores display when
+   * `EditorSession.setupEditor` mounts an image. */
+  display: none;
 }
 
 /* Editor SVG root.
@@ -186,13 +194,21 @@ body {
   height: 28px;
   background: var(--annot-bg-panel, #1e1e1e);
   border-top: 1px solid var(--annot-border-color, #333);
-  display: flex;
+  /* Hidden by default for the same reason as `#canvas-container`
+   * above — only the image editor mode shows the statusbar, and
+   * leaving it visible by default paints the dark bottom strip
+   * before JS resolves the route, contributing to the boot flash
+   * on gallery loads. `body.editor-mode` restores `display: flex`. */
+  display: none;
   align-items: center;
   padding: 0 12px;
   gap: 16px;
   font-size: 12px;
   color: #888;
 }
+body.editor-mode #statusbar {
+  display: flex;
+}
 
 /* Save toast notification */
 .save-toast {
@@ -970,6 +986,7 @@ body.editor-mode #editor-sidebar {
   overflow: visible;
 }
 body.editor-mode #canvas-container {
+  display: block;
   top: 48px; /* below editor-header only */
   left: 48px; /* right of the sidebar */
 }