@ingcreators/annot-core 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ingcreators/annot-core
 
+## 0.4.0
+
+### Minor Changes
+
+- Ship the metadata-unification surface to npm. The published 0.3.1
+  dist predates the whole track, so registry consumers were missing:
+  - XMP schema 2.0 — `buildXmp` restructured to an options object
+    (**breaking** for direct callers) with first-class provenance
+    fields (`sourceUrl` / `createdAt` / `producer` / `dpr`,
+    `XmpProvenance`), `ANNOT_XMP_VERSION = "2.0"`, XML-escaped
+    free-text fields, and `AnnotMetadata` gaining `version` +
+    provenance on the read side.
+  - `ELEMENT_TREE_ATTR_WHITELIST` in `/element-tree` — the canonical
+    attribute whitelist `@ingcreators/annot-product-docs@0.5.0`
+    imports (its registry install crashed with "does not provide an
+    export named 'ELEMENT_TREE_ATTR_WHITELIST'" until this release).
+  - SVG provenance helpers in `/editor/svg-format`
+    (`writeSvgProvenanceAttrs` / `readSvgProvenanceAttrs` /
+    `SVG_PROVENANCE_ATTRS`).
+
 ## 0.3.1
 
 ### Patch Changes

package/dist/editor/index.d.ts

@@ -2,7 +2,7 @@ export { createHistoryCore, DEFAULT_HISTORY_DEPTH, type HistoryCore, type Histor
 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';
+export { ANNOT_SVG_VERSION, ANNOT_SVG_VERSION_ATTR, ANNOT_SVG_VERSION_UNSTAMPED, getAnnotVersionFromString, readAnnotVersion, readSvgProvenanceAttrs, SVG_PROVENANCE_ATTRS, type SvgProvenance, stampAnnotVersion, writeSvgProvenanceAttrs, } from './svg-format.js';
 export { svgAnnotationsToShapes, svgElementToAnnotationShape, transformOf, translateOf, } from './svg-to-annotation-shapes.js';
 export { createMockToolSurface, type MockToolSurface, type ToolDOMSurface, } from './tool-lifecycle.js';
 export { selectionDefMetadata, TOOL_PANEL_ADAPTER_IDS, TOOL_PANEL_ADAPTERS, type ToolPanelAdapter, type ToolPanelAdapterId, type ToolPanelAdapterMetadata, } from './tool-panel-adapter.js';

package/dist/editor/svg-format.d.ts

@@ -66,3 +66,31 @@ export declare function readAnnotVersion(svgRoot: Element): string;
  * emits the attribute on the root well before any content).
  */
 export declare function getAnnotVersionFromString(svgString: string): string;
+/** Root-attribute names for the four provenance fields. */
+export declare const SVG_PROVENANCE_ATTRS: {
+    readonly sourceUrl: "data-annot-source-url";
+    readonly createdAt: "data-annot-created-at";
+    readonly producer: "data-annot-producer";
+    readonly dpr: "data-annot-dpr";
+};
+/** Provenance shape mirrored from `XmpProvenance` (annot-core/xmp). */
+export interface SvgProvenance {
+    sourceUrl?: string;
+    createdAt?: string;
+    producer?: string;
+    dpr?: number;
+}
+/**
+ * Write the provenance fields onto an SVG root element. Unset
+ * fields REMOVE their attribute so a re-save never leaves stale
+ * values behind. Call right before serializing a standalone
+ * `.annot.svg` — records embedded inside a raster's XMP packet
+ * don't need it (the packet itself is the carrier there).
+ */
+export declare function writeSvgProvenanceAttrs(root: Element, prov: SvgProvenance): void;
+/**
+ * Read the provenance fields back from an SVG root element.
+ * Missing attributes default to `""` / `0`, matching
+ * `AnnotMetadata`'s defensive-reader contract.
+ */
+export declare function readSvgProvenanceAttrs(root: Element): Required<SvgProvenance>;

package/dist/element-tree/attr-whitelist.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical HTML-attribute whitelist for `ElementNode.attributes` —
+ * Phase 7 of `docs/plans/metadata-unification.md`.
+ *
+ * Every ElementTree producer captures the SAME attribute set:
+ * the extension's MAIN-world walker, the Playwright
+ * `attachAttributes` adapter, and the product-docs fixture /
+ * migrator all derive from this constant (the walker's copy is
+ * inlined — `executeScript({func})` cannot import — and guarded by
+ * a behavioural symmetry test in `element-tree-walker.test.ts`).
+ *
+ * Selection principle: **`attributes` carries element shape (HTML
+ * attributes), `states` carries element state (ARIA / dynamic)** —
+ * aria-* never appears in `attributes`; producers encode those as
+ * `states` tokens instead.
+ *
+ * - Identity / locator hooks: `id`, `data-testid`, `data-test-id`,
+ *   `name` — `data-testid` is the i18n-stable match key the
+ *   living-spec roadmap designates; locator-building consumers
+ *   (MCP `resolve-locator`, future codegen) resolve against it at
+ *   use time. There is deliberately NO persisted `locator` field
+ *   on `ElementNode` (see the plan's Phase 7 decision log).
+ * - Navigation: `href`.
+ * - Form shape: `type`, `placeholder`, `value`, `required`,
+ *   `disabled`, `readonly`, `checked`, `maxlength`, `minlength`,
+ *   `pattern`, `min`, `max`, `step` — what a screen-specification
+ *   table documents per control.
+ */
+export declare const ELEMENT_TREE_ATTR_WHITELIST: readonly string[];

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

@@ -1,3 +1,4 @@
+export { ELEMENT_TREE_ATTR_WHITELIST } from './attr-whitelist.js';
 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';