@ingcreators/annot-core 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @ingcreators/annot-core
 
+## 0.3.1
+
+### Patch Changes
+
+- b47d896: **Publish the `./element-tree` subpath** — the published tarball now
+  serves `@ingcreators/annot-core/element-tree` (Tier A screen-capture
+  model + YAML / JSON serializers + walk/find utilities).
+
+  ### Root cause
+
+  `@ingcreators/annot-playwright`'s built `dist/index.js` externalises
+  its `@ingcreators/annot-core/element-tree` import, but core's
+  `publishConfig.exports` only mapped `.`, `./xmp-bytes`, and
+  `./styles/*` — the subpath resolved in the workspace (dev `exports`
+  map to `src/`) and failed for every registry consumer:
+
+  ```
+  Error: Package subpath './element-tree' is not defined by "exports"
+  in .../node_modules/@ingcreators/annot-core/package.json imported
+  from .../@ingcreators/annot-playwright/dist/index.js
+  ```
+
+  First observed in the workflow-app docs tour after the 0.4.1
+  publish repaired the `writeFile` dist crash — `playwright test`
+  now dies at config load before any test runs.
+
+  ### Fix
+  - `vite.config.ts` gains an `element-tree` library entry
+    (`src/element-tree/index.ts` → `dist/element-tree.js`).
+  - `publishConfig.exports` maps `./element-tree` to the built JS +
+    the emitted `dist/element-tree/index.d.ts`.
+
+  ### Verification
+  - `pnpm --filter @ingcreators/annot-core build` emits
+    `dist/element-tree.js` + `dist/element-tree/index.d.ts`.
+  - Packed tarball installed into a scratch project resolves
+    `import("@ingcreators/annot-core/element-tree")` and exposes the
+    full serializer / walk surface.
+
+## 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

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;