@ingcreators/annot-core 0.2.1 → 0.3.0

package/dist/storage/path.d.ts

@@ -20,6 +20,23 @@ export declare function joinPath(parent: string, name: string): string;
 export declare function getParentPath(path: string): string;
 /** Return the last segment (folder name or filename) from a path. */
 export declare function getFilename(path: string): string;
+/**
+ * Derive the annotations YAML sidecar path paired with the image
+ * at `pngPath`. Convention introduced in Phase 4a of the
+ * [living-spec authoring roadmap](../../../../docs/plans/living-spec-authoring-roadmap.md):
+ * the sidecar sits in the same folder as the PNG with filename
+ * `<pngFilename>.annotations.yaml`.
+ *
+ * Examples:
+ * - `shots/login.png` → `shots/login.png.annotations.yaml`
+ * - `login.jpg`       → `login.jpg.annotations.yaml`
+ *
+ * The leaf-as-suffix form (keep the full PNG filename including
+ * its extension, then append `.annotations.yaml`) keeps the
+ * sidecar discoverable next to its image regardless of the image
+ * extension.
+ */
+export declare function annotationsYamlPathFor(pngPath: string): string;
 /** Split a path into its segments. Returns [] for the root path. */
 export declare function splitPath(path: string): string[];
 /**

package/dist/storage/types.d.ts

@@ -1,9 +1,4 @@
-/**
- * Shared storage types used by Extension, Web app, and Desktop.
- *
- * Images and folders are identified by their filesystem-style path.
- * Root folder is represented by the empty string "".
- */
+import { ElementTree } from '../element-tree/types.js';
 export interface ImageRecord {
     /** Primary key: full path, e.g. "Screenshots/Mobile/image-123.png". */
     path: string;
@@ -18,12 +13,14 @@ export interface ImageRecord {
     tags: Record<string, string>;
     createdAt: string;
     updatedAt: string;
-    /** Optional DOM structure metadata captured alongside the screenshot
-     *  by the browser extension. Enables "click the Submit button →
-     *  auto-annotate" features in the editor. Undefined when the
-     *  capture came from a non-DOM source (desktop screenshot, paste,
-     *  etc.). Shape may evolve; see `PageMetadata.version`. */
-    pageMetadata?: PageMetadata;
+    /** Canonical screen-capture tree captured alongside the
+     *  screenshot. Source-agnostic: produced by the browser extension's
+     *  MAIN-world walker, by Playwright's adapter, or by any future
+     *  capture source (Figma adapter, OCR-derived, etc.). Undefined
+     *  when the capture came from a non-DOM source (desktop screenshot,
+     *  paste). Enables "click the Submit button → auto-annotate"
+     *  features in the editor. See `@ingcreators/annot-core/element-tree`. */
+    elementTree?: ElementTree;
 }
 /**
  * In-place updates allowed via `updateImage`. Note that `folderPath`
@@ -62,81 +59,6 @@ export interface ImageRecord {
  * dimensions actually changed.
  */
 export type ImageRecordUpdate = Partial<Pick<ImageRecord, "annotationsSvg" | "tags" | "updatedAt" | "originalDataUrl" | "width" | "height">>;
-export interface PageMetadata {
-    /** Schema version — bump on breaking changes so consumers can
-     *  gracefully handle old records. Current: 1. */
-    version: 1;
-    /** Source URL at capture time (also stored on ImageRecord.sourceUrl
-     *  but duplicated here so metadata is self-contained). */
-    url: string;
-    /** Viewport size at capture time, in CSS pixels (not device pixels).
-     *  Used to compute the scale factor when mapping bboxes onto the
-     *  screenshot (which is in device pixels). */
-    viewport: {
-        width: number;
-        height: number;
-    };
-    /** `window.devicePixelRatio` at capture time. */
-    devicePixelRatio: number;
-    /** For scroll / per-page captures: the scroll offset at capture
-     *  time. Single-viewport captures use `{ x: 0, y: 0 }`. Bboxes in
-     *  `elements` are in document coordinates; subtract this offset +
-     *  add again per-segment for stitched captures. */
-    scrollOffset: {
-        x: number;
-        y: number;
-    };
-    /** The rectangle of the document that the SCREENSHOT actually
-     *  covers, in CSS pixels, document coordinates. Used by the editor
-     *  to (a) FILTER `elements` to those visible in the screenshot
-     *  and (b) MAP element bboxes from doc coords → screenshot coords
-     *  via `(elBbox - captureRect.origin) * devicePixelRatio`.
-     *  - visible capture: equals viewport at capture time (scrollX/Y +
-     *    viewport size)
-     *  - area capture: the user-selected sub-region, offset by scroll
-     *  - scroll / per-page: full document (or per-segment) */
-    captureRect: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    /** ISO timestamp of when the metadata snapshot was taken (usually
-     *  within a few ms of the screenshot). */
-    capturedAt: string;
-    /** Detected elements. Filtered to interactive / labeled items (see
-     *  `interactiveRole` predicate in the content script). */
-    elements: PageElement[];
-}
-export interface PageElement {
-    /** Stable id within this capture — references across annotations. */
-    id: string;
-    /** Tag name in lowercase (e.g. "button", "a", "input"). */
-    tag: string;
-    /** ARIA role or implicit role ("button", "link", "textbox", ...). */
-    role?: string;
-    /** Visible text — textContent for button/link, label text for input. */
-    text?: string;
-    /** `aria-label` — explicit accessibility label, prefer over `text`
-     *  when present since it's the a11y ground truth. */
-    ariaLabel?: string;
-    /** For form inputs: the input type (text / email / submit / …). */
-    inputType?: string;
-    /** For inputs: placeholder text. */
-    placeholder?: string;
-    /** For links: the href destination. */
-    href?: string;
-    /** Element id attribute (if any) — useful for stable selection. */
-    domId?: string;
-    /** Bounding box in DOCUMENT (not viewport) coordinates at capture
-     *  time, in CSS pixels. To draw on the screenshot: multiply by
-     *  devicePixelRatio. [x, y, width, height]. */
-    bbox: [number, number, number, number];
-    /** CSS selector (best effort) for re-locating the element later. */
-    selector?: string;
-    /** True if element was (partially) visible at capture time. */
-    visible: boolean;
-}
 export interface FolderRecord {
     /** Primary key: full path, e.g. "Screenshots/Mobile". */
     path: string;
@@ -667,6 +589,53 @@ export interface StorageWithDocuments {
      * @throws `Error` for unstructured backend / IO failures.
      */
     updateDocument(path: string, updates: DocumentRecordUpdate): Promise<void>;
+    /**
+     * Read the annotations YAML sidecar paired with the image at
+     * `pngPath`. The store derives the sidecar location internally
+     * from the convention `<pngPath>.annotations.yaml` (so
+     * `shots/login.png` →`shots/login.png.annotations.yaml`); callers
+     * pass the PNG path only.
+     *
+     * Optional — stores that don't support sidecar yaml files may
+     * omit this method. Callers gate on
+     * {@link supportsAnnotationsYaml} before invoking.
+     *
+     * Introduced in Phase 4a of the
+     * [living-spec authoring roadmap](../../../../docs/plans/living-spec-authoring-roadmap.md)
+     * for the Annot editor's Overlay tool. Each entry in the yaml
+     * follows the `AnnotationsFile` schema defined by
+     * `@ingcreators/annot-product-docs` (Phase 2a).
+     *
+     * @returns the YAML source string, or `undefined` when no
+     *   sidecar exists for that PNG.
+     * @throws `Error` for backend / IO / parse failures.
+     */
+    getAnnotationsYaml?(pngPath: string): Promise<string | undefined>;
+    /**
+     * Atomically create or replace the annotations YAML sidecar
+     * paired with the image at `pngPath`. The store derives the
+     * sidecar location internally from the convention
+     * `<pngPath>.annotations.yaml`.
+     *
+     * Optional — stores that don't support sidecar yaml files may
+     * omit this method. Callers gate on
+     * {@link supportsAnnotationsYaml} before invoking.
+     *
+     * The write does NOT touch the PNG bytes or any sibling MDX
+     * file — only the sidecar yaml is mutated. Idempotent on
+     * unchanged input (same `content` twice produces the same
+     * on-disk bytes).
+     *
+     * Introduced in Phase 4a of the
+     * [living-spec authoring roadmap](../../../../docs/plans/living-spec-authoring-roadmap.md).
+     *
+     * @throws `StoragePermissionError` for backend auth / ACL
+     *   rejection.
+     * @throws `StorageQuotaError` when the backend reports
+     *   out-of-space.
+     * @throws `Error` for unstructured backend / IO failures.
+     */
+    setAnnotationsYaml?(pngPath: string, content: string): Promise<void>;
 }
 export declare function supportsResync(store: StorageProvider): store is StorageProvider & StorageWithResync;
 export declare function supportsForceRefresh(store: StorageProvider): store is StorageProvider & StorageWithForceRefresh;
@@ -675,3 +644,18 @@ export declare function supportsInit(store: StorageProvider): store is StoragePr
 export declare function supportsRateLimit(store: StorageProvider): store is StorageProvider & StorageWithRateLimit;
 export declare function supportsThumbnailCache(store: StorageProvider): store is StorageProvider & StorageWithThumbnailCache;
 export declare function supportsDocuments(store: StorageProvider): store is StorageProvider & StorageWithDocuments;
+/**
+ * Narrows a store to one that exposes the Phase 4a annotations
+ * YAML sidecar surface (`getAnnotationsYaml` + `setAnnotationsYaml`).
+ *
+ * Use instead of `if (store.getAnnotationsYaml)` so the narrow is
+ * type-safe and the optional behaviour is documented at the call
+ * site. The methods sit on
+ * {@link StorageWithDocuments} as optional members; this predicate
+ * is the dedicated capability check for callers that need both
+ * sides of the read / write pair.
+ */
+export declare function supportsAnnotationsYaml(store: StorageProvider): store is StorageProvider & StorageWithDocuments & {
+    getAnnotationsYaml: NonNullable<StorageWithDocuments["getAnnotationsYaml"]>;
+    setAnnotationsYaml: NonNullable<StorageWithDocuments["setAnnotationsYaml"]>;
+};

package/dist/xmp/element-tree-payload.d.ts

@@ -0,0 +1,32 @@
+import { ElementTree } from '../element-tree/index.js';
+/**
+ * iTXt chunk keyword identifying the ElementTree payload.
+ * Differs from the editor's XMP keyword (`XML:com.adobe.xmp`) so
+ * the two chunks can coexist on the same PNG.
+ */
+export declare const ELEMENT_TREE_ITXT_KEYWORD = "annot:elementTree";
+/**
+ * Write `tree` into a PNG's `annot:elementTree` iTXt chunk. The
+ * chunk is deflate-compressed (compressionFlag=1) — ElementTree YAML
+ * is verbose with high token repetition and compresses well.
+ *
+ * Any existing `annot:elementTree` chunk is replaced. Other chunks
+ * (image data, editor XMP, embedded original via `svGo`) are
+ * preserved verbatim.
+ */
+export declare function writeElementTreePng(pngData: Uint8Array, tree: ElementTree): Uint8Array;
+/**
+ * Read the `annot:elementTree` payload from a PNG. Returns the
+ * parsed `ElementTree`, or `null` when the input is not a PNG or
+ * has no `annot:elementTree` chunk.
+ *
+ * Throws on schema-version mismatch (unknown major version) or
+ * parse failure — silent ignore would mask data corruption. Callers
+ * that need a tolerant read should wrap in try / catch.
+ */
+export declare function readElementTreePng(pngData: Uint8Array): ElementTree | null;
+/**
+ * Light-weight predicate — does this PNG carry an
+ * `annot:elementTree` chunk at all? Doesn't deflate or parse.
+ */
+export declare function hasElementTreePng(pngData: Uint8Array): boolean;

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

@@ -14,7 +14,7 @@
  * 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 { type AnnotMetadata, type CreateEditablePngBytesOptions, createEditablePngBytes, dataUrlToUint8Array, readEditableImage, readEditablePngBytes, WELL_KNOWN_TAG_KEYS, writePngWithTagsOnly, } from './xmp-bytes.js';
 export interface EditableImageOptions {
     /** Rendered image (screenshot + annotations) as Blob */
     renderedBlob: Blob;

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

@@ -16,8 +16,37 @@
  *       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 u32be(n: number): Uint8Array;
+export declare function readU32be(data: Uint8Array, offset: number): number;
+export declare function concat(...arrays: Uint8Array[]): Uint8Array;
+export declare function startsWith(data: Uint8Array, offset: number, prefix: Uint8Array): boolean;
 export declare function dataUrlToUint8Array(dataUrl: string): Uint8Array;
 export declare function writeJpegWithMetadata(jpegData: Uint8Array, xmpBytes: Uint8Array, originalData: Uint8Array): Uint8Array;
+export declare function crc32(data: Uint8Array): number;
+export declare function buildPngChunk(chunkType: Uint8Array, data: Uint8Array): Uint8Array;
+/**
+ * Strip the Annot editor's editable-layer metadata from a PNG.
+ * Walks the chunk stream, drops the Adobe XMP iTXt chunk (the
+ * `<annot:annotations>` / `<annot:tags>` carrier) AND the custom
+ * `svGo` chunk (the original un-annotated bitmap), keeps every
+ * other chunk verbatim (including all critical chunks IHDR /
+ * IDAT / IEND so the result stays a valid PNG with the same
+ * visible pixels).
+ *
+ * Returns the input bytes unchanged when no editable-layer
+ * chunks are present.
+ *
+ * Used internally by `writePngWithMetadata` / `writePngWithTagsOnly`
+ * to clear stale metadata before re-injecting new chunks. Exposed
+ * since Phase 3j of `docs/plans/living-spec-authoring-roadmap.md`
+ * (Phase 3 follow-up #2) so `@ingcreators/annot-annotator` can
+ * publish a top-level `flattenEditablePng` primitive against the
+ * same logic without duplicating chunk-walking code.
+ *
+ * No re-rasterization — the visible bytes were already the
+ * annotated bitmap; this is metadata removal only.
+ */
+export declare function stripPngEditableLayer(data: Uint8Array): Uint8Array;
 export declare function writePngWithMetadata(pngData: Uint8Array, xmpBytes: Uint8Array, originalData: Uint8Array): Uint8Array;
 /**
  * Build a tags-only XMP packet — `<annot:tags>` element present,

package/dist/xmp-bytes.js

@@ -79,7 +79,7 @@ function g(e, t, r) {
 	return u(o.slice(0, 2), i, a, o.slice(2));
 }
 var _ = (() => {
-	let e = new Uint32Array(256);
+	let e = /* @__PURE__ */ new Uint32Array(256);
 	for (let t = 0; t < 256; t++) {
 		let n = t;
 		for (let e = 0; e < 8; e++) n & 1 ? n = 3988292384 ^ n >>> 1 : n >>>= 1;
@@ -262,4 +262,4 @@ function z(e) {
 	return btoa(n);
 }
 //#endregion
-export { T as WELL_KNOWN_TAG_KEYS, a as buildXmp, C as buildXmpTagsOnly, E as createEditablePngBytes, f as dataUrlToUint8Array, O as readEditableImage, D as readEditablePngBytes, g as writeJpegWithMetadata, S as writePngWithMetadata, w as writePngWithTagsOnly };
+export { T as WELL_KNOWN_TAG_KEYS, y as buildPngChunk, a as buildXmp, C as buildXmpTagsOnly, u as concat, v as crc32, E as createEditablePngBytes, f as dataUrlToUint8Array, O as readEditableImage, D as readEditablePngBytes, l as readU32be, d as startsWith, x as stripPngEditableLayer, s as u32be, g as writeJpegWithMetadata, S as writePngWithMetadata, w as writePngWithTagsOnly };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-core",
-  "version": "0.2.1",
+  "version": "0.3.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",
@@ -46,12 +46,14 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/pako": "^2.0.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.1"
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.3"
   },
   "dependencies": {
+    "js-yaml": "^4.1.1",
     "pako": "^2.1.0"
   },
   "scripts": {