@ingcreators/annot-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,152 @@
 # @ingcreators/annot-core
 
+## 0.3.0
+
+### Minor Changes
+
+- 691bec5: **Add `flattenEditablePng(pngBytes) → pngBytes`** — Phase 3j of
+  `docs/plans/living-spec-authoring-roadmap.md` (Phase 3
+  follow-up #2). The editor's editable-PNG format embeds the
+  original un-annotated capture + the annotations SVG in PNG
+  ancillary chunks for re-edit; "flatten" drops those chunks and
+  keeps just the visible (already-annotated) bytes.
+
+  ### `@ingcreators/annot-annotator` — new public surface
+
+  ```ts
+  import { flattenEditablePng } from "@ingcreators/annot-annotator";
+
+  const flat = flattenEditablePng(editablePngBytes);
+  // → flat PNG: same visible pixels, no Adobe XMP iTXt chunk,
+  //   no custom svGo chunk. `readEditablePngBytes(flat)` returns
+  //   null. File size drops significantly (the editable layer
+  //   roughly doubled the bytes).
+  ```
+
+  ### `@ingcreators/annot-core/xmp-bytes` — new public surface
+
+  The implementation lives in `@ingcreators/annot-core` as
+  `stripPngEditableLayer` — the same chunk-walking helper that
+  `writePngWithMetadata` / `writePngWithTagsOnly` already used
+  internally to clean stale metadata before re-injecting. Now
+  exported so other Tier A consumers (not just annotator) can
+  use it directly.
+
+  annotator's `flattenEditablePng` is a one-line wrapper that
+  calls `stripPngEditableLayer` under a more user-facing name.
+
+  ### Why this is metadata removal, not re-rasterization
+
+  `toEditablePng` rasterizes the SVG fragment onto the base image
+  FIRST and embeds the editable layer as ancillary PNG chunks
+  (`iTXt` carrying Adobe XMP + custom `svGo` chunk). The visible
+  bytes are already the annotated bitmap. Flattening strips the
+  ancillary chunks; the IDAT pixel data stays byte-identical.
+  No decode, no re-encode, no `@napi-rs/canvas` round-trip.
+
+  ### Use cases
+  - **Publish-flat** — editor session → distribution-ready PNG;
+    the editable layer is dead weight for downstream consumers
+    (Slack drop, third-party viewers).
+  - **File size** — editable PNG roughly doubles in bytes
+    (original + SVG embedded); flattening drops the overhead.
+  - **Privacy hardening** — `burnRedactions` is the strong
+    version for _redact_ regions; flattening drops the
+    recoverable original entirely for _all_ annotations,
+    including non-redact ones whose annotated visual the
+    publisher wants to keep but whose original capture they
+    don't want shippable.
+
+  ### Internal rename in annot-core
+
+  The private `removePngMetadata` helper in
+  `@ingcreators/annot-core/xmp-bytes` is renamed to
+  `stripPngEditableLayer` (clearer name describing what it does
+  rather than how it's used). Internal callers in the same
+  module updated. No external API change for the rename itself;
+  `writePngWithMetadata` + `writePngWithTagsOnly` keep their
+  existing signatures + behaviour.
+
+  ### Compatibility
+
+  Additive on annotator + core. No behaviour change for existing
+  callers (the only internal rename is a private helper).
+
+## 0.2.1
+
+### Patch Changes
+
+- f485646: **Expose `./xmp-bytes` subpath on the published tarball.**
+  The workspace `package.json#exports` declared
+  `"./xmp-bytes": "./src/xmp/xmp-bytes.ts"` from day one, but
+  `publishConfig.exports` only declared `.` + `./styles/*` —
+  so every workspace subpath (`./headless`, `./editor/*`,
+  `./xmp-bytes`, etc.) was stripped from the published
+  tarball.
+
+  This patch unblocks the `./xmp-bytes` subpath specifically.
+  `@ingcreators/annot-product-docs-astro@0.2.1`'s playwright
+  fixture imports `@ingcreators/annot-core/xmp-bytes` (via
+  the bundled `writePngWithTagsOnly` helper); without this
+  patch, any consumer doing
+  `import { test } from "@ingcreators/annot-product-docs-astro/playwright"`
+  hits `Package subpath './xmp-bytes' is not defined`.
+
+  ## Fix
+
+  `vite.config.ts` switches to multi-entry library mode:
+
+  ```ts
+  lib: {
+    entry: {
+      index: resolve(__dirname, "src/index.ts"),
+      "xmp-bytes": resolve(__dirname, "src/xmp/xmp-bytes.ts"),
+    },
+    formats: ["es"],
+  },
+  ```
+
+  `package.json#publishConfig.exports` gains the matching
+  `./xmp-bytes` entry:
+
+  ```json
+  "./xmp-bytes": {
+    "types": "./dist/xmp/xmp-bytes.d.ts",
+    "default": "./dist/xmp-bytes.js"
+  }
+  ```
+
+  Bundle landing in the tarball:
+
+  ```
+  dist/xmp-bytes.js          7.55 kB │ gzip: 2.67 kB
+  dist/xmp/xmp-bytes.d.ts    declarations colocated by the dts plugin
+  ```
+
+  ## Other subpaths still missing
+
+  The workspace `exports` map declares 17+ subpaths (`./headless`,
+  `./editor`, `./editor/*`, `./icons`, `./xmp`, `./zip`,
+  `./utils`, `./desktop-bridge`, `./storage`, `./encode/*`,
+  `./auto-capture-options`, …). Most are Tier C (browser-only)
+  and shouldn't ship as standalone published bundles — Tier C
+  code lives in `@ingcreators/annot-editor` / `-render` for
+  npm consumers. The few Tier A subpaths that DO make sense
+  on npm (`./headless`, `./storage`, `./utils`, `./zip`,
+  `./zip-bytes`) can ship in a separate follow-up patch
+  when a concrete downstream consumer needs them.
+
+  ## After this PR republishes
+
+  `@ingcreators/annot-product-docs-astro` needs a `0.2.2`
+  republish that bumps its `@ingcreators/annot-core` dep
+  from `0.2.0` to `^0.2.1` so the playwright fixture can
+  finally resolve `./xmp-bytes` at consumer install time.
+  Once both land, the `examples/workflow-app/` tour can
+  migrate from the hybrid `captureScreen + page.screenshot`
+  pair to the unified `page.screenshot({ annot: { mdx } })`
+  single call.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -40,7 +40,7 @@ headless tool against the SDK.
 |---------|------|---------|---|
 | `@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/storage` | A | `ImageRecord`, `FolderRecord`, `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) |

package/dist/editor/index.d.ts

@@ -1,4 +1,5 @@
 export { createHistoryCore, DEFAULT_HISTORY_DEPTH, type HistoryCore, type HistoryHooks, } from './history-core.js';
+export type { OverlayRegionPickDetail } from './overlay-pick-types.js';
 export { CATEGORY_CONTROL_SHAPE, classifyPropertyElement, classifyPropertySelection, PROPERTY_CONTROL_IDS, PROPERTY_CONTROLS, PROPERTY_EFFECT_IDS, type PropertyCategory, type PropertyControlDef, type PropertyControlId, type PropertyControlOption, type PropertyControlType, type PropertyEffectId, } from './property-schema.js';
 export { computeSnap, cursorForAngle, type Rect, rotateAround, type SnapGuide, type SnapInput, type SnapResult, } from './selection-geometry.js';
 export { ANNOT_SVG_VERSION, ANNOT_SVG_VERSION_ATTR, ANNOT_SVG_VERSION_UNSTAMPED, getAnnotVersionFromString, readAnnotVersion, stampAnnotVersion, } from './svg-format.js';

package/dist/editor/overlay-pick-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared types for the snapshot region pick flow — Phase 4d of
+ * [`docs/plans/living-spec-authoring-roadmap.md`](../../../../docs/plans/living-spec-authoring-roadmap.md).
+ *
+ * The `<annot-snapshot-overlay>` Lit element (host-ui) and the
+ * `OverlayTool` (editor) both deal with snapshot-region picks but
+ * live in packages that don't depend on each other (host-ui →
+ * editor, not the reverse). Lifting the detail type into Tier A
+ * core lets both sides import it without forcing a cycle.
+ *
+ * Pure data types — no DOM, no Node-specific APIs.
+ */
+/**
+ * Payload of the `overlay-region-pick` CustomEvent fired by
+ * `<annot-snapshot-overlay>` when the user clicks a region.
+ * Consumed by `OverlayTool` to build an `OverlayProposal` for the
+ * intent picker dialog.
+ */
+export interface OverlayRegionPickDetail {
+    /** Tree-unique identifier of the picked node (e.g. `"e3"`).
+     *  Stable within one capture only — annotation persistence keys
+     *  on `match: { role, name }` instead. */
+    ref: string;
+    /** ARIA role of the picked node. Always present. */
+    role: string;
+    /** Accessible name, when the node carries one. */
+    name?: string;
+    /** Page-space bounding box of the picked node. CSS px. */
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

package/dist/editor/tool-registry.d.ts

@@ -316,5 +316,5 @@ export declare function normalizeVariantSideFields(toolId: string, newVariant: s
 export declare const TOOL_REGISTRY: Readonly<Record<string, ToolRegistryEntry>>;
 /** All tool ids the toolbar exposes. Frozen tuple form for tests
  *  that assert the registry covers exactly this set. */
-export declare const TOOL_REGISTRY_IDS: readonly ["arrow", "shape", "highlight", "text", "freehand", "marker", "redact", "crop"];
+export declare const TOOL_REGISTRY_IDS: readonly ["arrow", "shape", "highlight", "text", "freehand", "marker", "redact", "crop", "overlay"];
 export type ToolRegistryId = (typeof TOOL_REGISTRY_IDS)[number];

package/dist/element-tree/index.d.ts

@@ -0,0 +1,4 @@
+export { parseElementTreeFromJson, serializeElementTreeToJson, validateElementTree, } from './json.js';
+export { type BBox, type ElementNode, type ElementTree, type ElementTreeSource, type ElementTreeViewport, isElementTreeShape, } from './types.js';
+export { type ElementMatch, type ElementTreeVisitor, findByMatch, findByRef, flattenTree, walkTree, } from './walk.js';
+export { parseElementTreeFromYaml, serializeElementTreeToYaml } from './yaml.js';

package/dist/element-tree/json.d.ts

@@ -0,0 +1,21 @@
+import { ElementTree } from './types.js';
+/**
+ * Serialize an ElementTree to a JSON string. Uses 2-space indent for
+ * readability; pass `compact: true` for a single-line minified
+ * form. Optional / undefined fields are omitted from the output to
+ * keep the serialization round-trip stable.
+ */
+export declare function serializeElementTreeToJson(tree: ElementTree, options?: {
+    compact?: boolean;
+}): string;
+/**
+ * Parse a JSON string into an ElementTree. Throws `Error` with a
+ * descriptive message on malformed input — the parser is strict to
+ * surface schema drift early.
+ */
+export declare function parseElementTreeFromJson(json: string): ElementTree;
+/**
+ * Strict structural validation of a parsed `unknown` payload.
+ * Exported so the YAML parser can share the same validation pass.
+ */
+export declare function validateElementTree(value: unknown): ElementTree;

package/dist/element-tree/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Top-level ElementTree wire format. Stored in PNG XMP as iTXt
+ * (`annot:elementTree` keyword, deflate-compressed YAML by default —
+ * see `@ingcreators/annot-core/xmp` extension landed in Phase 1d).
+ */
+export interface ElementTree {
+    /** Schema version. Currently 1. Reader version-dispatches; writers
+     *  always emit the current schema. */
+    version: 1;
+    /** Metadata about who produced this capture. */
+    source: ElementTreeSource;
+    /** Capture viewport. CSS px; `scale` is the device-pixel-ratio. */
+    viewport: ElementTreeViewport;
+    /** Root node. Always present. Often `role: "main"` or `"document"`
+     *  for browser captures; for partial captures (area / element-scoped)
+     *  the root is the captured element itself. */
+    root: ElementNode;
+}
+export interface ElementTreeSource {
+    /** Which capture tool produced this tree. Common values:
+     *  `"extension"` (browser extension MAIN-world walker),
+     *  `"playwright"` (ariaSnapshot adapter). Open-ended so future
+     *  Figma / screen-recorder / OCR adapters slot in cleanly. */
+    kind: "extension" | "playwright" | (string & {});
+    /** ISO 8601 timestamp of when the tree was produced. */
+    capturedAt: string;
+    /** Optional human-readable tool identifier (e.g.
+     *  `"annot-playwright@0.4.0"`). Used in `annot show-xmp` output for
+     *  debug; not consumed programmatically. */
+    agent?: string;
+    /** Source page URL at capture time, if applicable. */
+    url?: string;
+}
+export interface ElementTreeViewport {
+    /** Viewport width in CSS px. */
+    width: number;
+    /** Viewport height in CSS px. */
+    height: number;
+    /** `window.devicePixelRatio` (or equivalent) at capture time. Used
+     *  to map CSS-px bboxes onto device-px screenshot coordinates. */
+    scale: number;
+}
+/**
+ * Per-node payload. Children are nested in `children`; the tree is
+ * walked depth-first.
+ */
+export interface ElementNode {
+    /** ARIA role. Always present — decorative nodes use `"generic"` or
+     *  `"presentation"`. Browser captures fall back to the implicit
+     *  role for the underlying tag when ARIA doesn't apply. */
+    role: string;
+    /** Accessible name. Omitted when empty. */
+    name?: string;
+    /** Page-space bounding box in CSS px. Omitted for hidden / abstract
+     *  nodes (e.g. document root with no measurable extent). */
+    bbox?: BBox;
+    /** Tree-unique identifier in `e<n>` format (depth-first numbering
+     *  starting at `e1`). Stable WITHIN one capture; NOT stable across
+     *  re-captures — see OQ-11 in the roadmap. */
+    ref: string;
+    /** ARIA-derived state tokens. Single tokens like `"checked"`,
+     *  `"pressed"`, `"expanded"`, `"selected"`, `"disabled"`,
+     *  `"required"`, `"invalid"`. Also accepts `key=value` tokens for
+     *  scalar states: `"level=2"`, `"valuetext=10"`. */
+    states?: readonly string[];
+    /** HTML attribute snapshot (whitelist-filtered at capture time).
+     *  Keys are lowercase attribute names; values are the attribute
+     *  strings. Empty when no attributes were captured. */
+    attributes?: Readonly<Record<string, string>>;
+    /** Direct text content (heading body, paragraph text, textbox
+     *  value). Distinct from `name` for elements where they differ
+     *  (e.g. a textbox with placeholder `"Email"` and current value
+     *  `"alice@example.com"` has `name: "Email"`, `text:
+     *  "alice@example.com"`). */
+    text?: string;
+    /** Children in document order. Omitted for leaf nodes. */
+    children?: readonly ElementNode[];
+}
+/**
+ * Axis-aligned bounding box. CSS px, page-space coordinates.
+ */
+export interface BBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Convenience type guard for callers that receive `unknown` payloads
+ * and need to check whether they look like an ElementTree before
+ * narrowing. Light validation only — checks for the presence of the
+ * three required top-level keys plus `version === 1`. The full
+ * parsers (`parseElementTreeFromYaml` / `parseElementTreeFromJson`)
+ * do exhaustive structural validation.
+ */
+export declare function isElementTreeShape(value: unknown): value is ElementTree;

package/dist/element-tree/walk.d.ts

@@ -0,0 +1,49 @@
+import { ElementNode, ElementTree } from './types.js';
+/**
+ * Visitor callback. Return `false` to stop traversal early; return
+ * `void` / `true` to keep walking. The `parents` array gives the
+ * ancestor chain from the root down to (but excluding) the visited
+ * node — empty for the root itself.
+ */
+export type ElementTreeVisitor = (node: ElementNode, parents: readonly ElementNode[]) => boolean | void;
+/**
+ * Depth-first walk over every node in the tree. Stops early when the
+ * visitor returns `false`.
+ */
+export declare function walkTree(tree: ElementTree, visit: ElementTreeVisitor): void;
+/**
+ * Find the unique node with the given `ref`, or `null` if none.
+ * Refs are tree-unique within one capture (depth-first numbering),
+ * so the first match is the only match.
+ */
+export declare function findByRef(tree: ElementTree, ref: string): ElementNode | null;
+/**
+ * Match descriptor used by annotation yaml's `match: { role, name }`
+ * resolver. Both fields optional independently — a `{ role: "main" }`
+ * match catches every node with that role regardless of name; a
+ * `{ name: "Sign in" }` catches every node with that name regardless
+ * of role. When both are set, both must match (AND semantics). `name`
+ * comparison is exact.
+ */
+export interface ElementMatch {
+    role?: string;
+    name?: string;
+}
+/**
+ * Find every node satisfying the match. Returns nodes in
+ * depth-first document order.
+ *
+ * Returning all matches (not just the first) lets callers detect
+ * ambiguity — drift detection flags `duplicated` when a unique
+ * `match` resolves to more than one node.
+ */
+export declare function findByMatch(tree: ElementTree, match: ElementMatch): ElementNode[];
+/**
+ * Produce a flat array of every node in depth-first document order.
+ * Each entry is the live `ElementNode` reference (no copying); the
+ * caller must treat the result as read-only.
+ *
+ * Useful for consumers that prefer flat iteration (search index
+ * builders, etc.). Prefer `walkTree` when ancestor context matters.
+ */
+export declare function flattenTree(tree: ElementTree): ElementNode[];

package/dist/element-tree/yaml.d.ts

@@ -0,0 +1,22 @@
+import { ElementTree } from './types.js';
+/**
+ * Serialize an ElementTree to YAML.
+ *
+ * The output uses 2-space indent, sorted top-level keys, and
+ * deterministic field ordering inside each node so the same tree
+ * always serializes to byte-identical YAML. This is important for
+ * the XMP write path — re-saving a PNG without semantic changes
+ * must produce identical bytes, otherwise git history thrashes
+ * pointlessly.
+ *
+ * Empty optional fields (`states`, `attributes`, `children`) are
+ * omitted entirely. The reader treats absence and empty as
+ * equivalent.
+ */
+export declare function serializeElementTreeToYaml(tree: ElementTree): string;
+/**
+ * Parse a YAML string into an ElementTree. Throws `Error` with a
+ * descriptive message on malformed input (parse failure or schema
+ * mismatch).
+ */
+export declare function parseElementTreeFromYaml(yaml: string): ElementTree;

package/dist/headless.d.ts

@@ -14,16 +14,18 @@ export { normalizeVariantSideFields, TOOL_PANEL_EXTRA_CONTROL_IDS, TOOL_REGISTRY
 export { readUniversalStyleAttrs, resolveStyleReadSource, } from './editor/tool-style-reader.js';
 export { writeUniversalStyleAttrs } from './editor/tool-style-writer.js';
 export { type AffineMatrix, applyInverseAffine, clampZoom, computeFitZoom, computeRenderedSize, DEFAULT_MAX_ZOOM, DEFAULT_MIN_ZOOM, FIT_VIEW_PADDING, } from './editor/viewport-math.js';
+export { type BBox, type ElementMatch, type ElementNode, type ElementTree, type ElementTreeSource, type ElementTreeViewport, type ElementTreeVisitor, findByMatch, findByRef, flattenTree, isElementTreeShape, parseElementTreeFromJson, parseElementTreeFromYaml, serializeElementTreeToJson, serializeElementTreeToYaml, validateElementTree, walkTree, } from './element-tree/index.js';
 export { builtinIcon, type IconSpec, isBuiltinIcon, isSvgIcon, isUrlIcon, svgIcon, urlIcon, } from './icons/types.js';
 export { StorageConflictError, StorageError, type StorageErrorCode, StorageNotFoundError, StoragePermissionError, StorageQuotaError, } from './storage/errors.js';
 export { type ListingEntry, type ListingEntryKind, type MetadataCache, MetadataCacheError, MetadataCacheQuotaError, type StorageWithMetadataCache, supportsMetadataCache, } from './storage/metadata-cache.js';
 export { ancestorPaths, getFilename, getParentPath, isDescendantOrSame, joinPath, ROOT_PATH, rewritePathPrefix, splitExt, splitPath, uniquifyFilename, uniquifyFilenameAsync, validateName, } from './storage/path.js';
 export { type CachedThumbnail, type ThumbnailCache, ThumbnailCacheError, type ThumbnailCacheGetRequest, ThumbnailCacheQuotaError, } from './storage/thumbnail-cache.js';
-export type { DocumentRecord, DocumentRecordUpdate, FolderRecord, ImageRecord, ImageRecordUpdate, PageElement, PageMetadata, StorageProvider, StorageWithDocuments, StorageWithForceRefresh, StorageWithInit, StorageWithRateLimit, StorageWithResync, StorageWithTokenRefresher, } from './storage/types.js';
+export type { DocumentRecord, DocumentRecordUpdate, FolderRecord, ImageRecord, ImageRecordUpdate, StorageProvider, StorageWithDocuments, StorageWithForceRefresh, StorageWithInit, StorageWithRateLimit, StorageWithResync, StorageWithTokenRefresher, } from './storage/types.js';
 export { supportsDocuments, supportsForceRefresh, supportsInit, supportsRateLimit, supportsResync, supportsTokenRefresher, } from './storage/types.js';
 export { assertNonNull } from './utils/assert.js';
 export { DEFAULT_FILL_COLOR, DEFAULT_FONT_SIZE, DEFAULT_STROKE_COLOR, DEFAULT_STROKE_WIDTH, JPEG_QUALITY, MOSAIC_BLOCK_SIZE, } from './utils/constants.js';
 export { computeDasharray, detectDashKey } from './utils/dash-utils.js';
 export { ANNOT_FILENAME_PREFIX, defaultAnnotFilenameStem, defaultAnnotImageFilename, formatLocalTimestamp, } from './utils/filename.js';
 export { newIdB58 } from './utils/id.js';
+export { ELEMENT_TREE_ITXT_KEYWORD, hasElementTreePng, readElementTreePng, writeElementTreePng, } from './xmp/element-tree-payload.js';
 export { buildZip, dataUrlExt, dataUrlToBytes } from './zip/zip-builder.js';