@ingcreators/annot-product-docs 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,268 @@
 # @ingcreators/annot-product-docs
 
+## 0.4.0
+
+### Minor Changes
+
+- b5d52f6: **Annotation palette composes onto the annotated PNG** — Phase 3c
+  of `docs/plans/living-spec-authoring-roadmap.md`. The Astro Image
+  Service's `renderAnnotatedScreen` now reads the Phase 3a yaml
+  `annotations[]` section and bakes the full visual palette
+  (rect / circle / arrow / text / callout / freehand / redact /
+  focusMask) onto the base PNG, layered underneath the existing
+  numbered-badge overlays.
+
+  ### New public surface — `@ingcreators/annot-product-docs`
+
+  `buildShapeAnnotationsFromYaml(annotations, boxed, dims) →
+BboxAnnotation[]` maps each Phase 3a `AnnotationSpec` against the
+  page's `BoxedEntry[]` (from snapshot YAML or PNG XMP ElementTree)
+  and produces `BboxAnnotation` shapes the headless annotator's
+  `bboxAnnotationsToSvg` consumes. Per-variant resolution:
+  - **`rect`** — `match` / `coversElements[]` / `bbox`. `coversElements`
+    unions the per-element bboxes into one.
+  - **`circle`** — match-anchored circles centre on the element bbox
+    with radius defaulting to half the longer axis; `center` + `radius`
+    is the free-coord form.
+  - **`arrow`** — endpoints can be `{ match }` (centre-to-centre) or
+    `{ point }`.
+  - **`text`** — `anchor.position` (above / below / left / right /
+    center) offsets a centred / left- / right-anchored label by 8 px
+    outside the element bbox.
+  - **`callout`** — target = match-resolved or free-coord bbox; `at`
+    is the caption position.
+  - **`freehand`** — passes through verbatim.
+  - **`redact`** — style: `solid` renders as a filled rect (default
+    fill `#222222`, no stroke); `fill` / `stroke` overrides honoured.
+  - **`focusMask`** — cutout expands by `padding` (match-anchored);
+    outer rect collapses to the supplied image dims.
+
+  Intent mapping mirrors the existing badge path
+  (`required → error`, `action → warning`, others pass through).
+
+  Match resolution failures are silently skipped — the drift
+  detector (Phase 3d) surfaces them upstream so the build keeps
+  producing a useful PNG even when the snapshot has drifted.
+
+  ### Behaviour change — `renderAnnotatedScreen`
+
+  When `<Screen annotations="…">` resolves to a yaml carrying
+  `annotations[]`, the renderer composes shapes (underneath) + badges
+  (on top) into one SVG fragment via `svgFromBboxAnnotations`. The
+  cache key already includes the annotations-yaml source from
+  Phase 2b, so edits to the yaml bust the cached PNG without extra
+  bookkeeping. Pre-Phase-3 yaml files (no `annotations` key) parse
+  - render unchanged.
+
+  ### Compatibility
+
+  Additive. Existing callers that only use `overlays[]` see no
+  behaviour change. The new `buildShapeAnnotationsFromYaml` export
+  is opt-in.
+
+- fa712fd: **Annotation palette drift + xlsx coverage (Phase 3d)** — closes
+  Phase 3 of `docs/plans/living-spec-authoring-roadmap.md`.
+
+  ### Drift detector — `yamlAnnotations` opt-in
+
+  `detectDrift` / `detectDriftFromYaml` / `detectDriftFromElementTree`
+  gain an optional `yamlAnnotations: readonly AnnotationSpec[]`
+  field. When set, the detector walks the match keys reachable from
+  each Phase 3a `AnnotationSpec` (via the new
+  `collectMatchKeysFromAnnotation(spec) → MatchKey[]` helper) and
+  runs them through the same match-cycle as overlays — emitting
+  `removed` / `renamed` / `role-changed` / `duplicated` findings
+  with the annotation `id` referenced in the message.
+
+  Free-coord variants (`bbox`-only rect / `point`-only arrow
+  endpoint / `at`-only text / `bbox`-only callout target /
+  freehand / `bbox`-only redact / `bbox`-only focusMask cutout)
+  contribute zero keys and pass through silently.
+
+  `annotations[]` IDs are NEVER referenced from `<AnnotCallout for>`
+  (overlays[] owns that contract), so no
+  `description-missing` / `description-orphan` findings fire for
+  this source.
+
+  ### Excel adapter — yaml-driven rows for migrated screens
+
+  `@ingcreators/annot-product-docs-xlsx`'s `extractFromParsed`
+  gains an optional `annotationsYamlByPath` context map. When a
+  `<Screen>` carries `annotations="…"` and the matching yaml is in
+  the map, the item-table rows are sourced from the yaml's
+  `overlays[]` (each row's body cross-referenced from
+  `screen.callouts` by id). `extractMdxFile` loads each
+  referenced yaml file from disk automatically — missing files are
+  a loud failure on the same "explicit reference, but file gone"
+  reasoning the Astro Image Service uses.
+
+  `annotations[]` entries in the yaml are deliberately NOT
+  surfaced as rows. The Astro Image Service composes them onto
+  the annotated PNG; the Excel adapter renders the resulting image
+  in the spreadsheet's picture column while the items table stays
+  scoped to overlays.
+
+  ### workflow-app dogfood
+
+  `examples/workflow-app/docs/books/operation-manual/OM-001-login.mdx`
+  migrates from inline `<Overlay>` to the
+  `<Screen annotations="./OM-001-login.annotations.yaml">` +
+  `<AnnotCallout for>` form. The companion yaml ships three
+  overlays plus three `annotations[]` entries exercising
+  `rect` + `arrow` + `focusMask` — the full Phase 3 palette
+  end-to-end through the workflow-app's docs build.
+
+  ### Compatibility
+
+  Additive. Existing drift callers see no behaviour change unless
+  they opt in to `yamlAnnotations`. Existing xlsx callers see no
+  behaviour change unless they migrate a screen to the yaml form;
+  inline-`<Overlay>` screens continue to drive rows as before.
+
+- f09a6b1: **Annotation yaml `redact.style` accepts `mosaic` / `blur`** —
+  Phase 3f of `docs/plans/living-spec-authoring-roadmap.md`
+  (Phase 3 follow-up).
+
+  The Phase 3a parser shipped `redact.style: "solid"` only; mosaic
+  / blur were explicitly rejected with a "reserved for follow-up"
+  message. Phase 3f widens the enum to all three (`solid` /
+  `mosaic` / `blur`) so authoring tools and the Astro Image
+  Service can use the values end-to-end.
+
+  ### Parser behaviour
+
+  ```yaml
+  # Phase 3a: accepted
+  annotations:
+    - id: redact-1
+      kind: redact
+      bbox: { x: 0, y: 0, width: 100, height: 30 }
+      style: solid
+
+  # Phase 3f: NEW — both accepted
+  annotations:
+    - id: redact-2
+      kind: redact
+      match: { role: textbox, name: Reason }
+      style: mosaic
+    - id: redact-3
+      kind: redact
+      bbox: { x: 421, y: 269, width: 438, height: 40 }
+      style: blur
+  ```
+
+  Unknown style values still error with an updated message:
+  `redact.style must be one of "solid" / "mosaic" / "blur"`.
+
+  ### Render behaviour (transitional)
+
+  Between 3f (this PR) and 3g (Astro Image Service raster
+  pre-processing), `mosaic` and `blur` redact entries are
+  parser-accepted but the Image Service still routes them
+  through the SVG-fragment filled-rect path — so they LOOK
+  identical to `solid` until 3g lands. 3g wires the raster
+  pass that gives `mosaic` / `blur` their distinct visual
+  output.
+
+  ### New public type
+
+  `RedactAnnotationStyle` (the `"solid" | "mosaic" | "blur"` union)
+  is exported from `@ingcreators/annot-product-docs` so callers
+  can reference it directly.
+
+  ### Compatibility
+
+  Additive within v1. Pre-3f files (no redact entries, or
+  `style: solid` only) parse identically. Files authored with
+  `style: "mosaic" | "blur"` are rejected by the pre-3f parser
+  (loud failure pointing at the unsupported style) — consumers
+  on older `@ingcreators/annot-product-docs` upgrade to consume
+  the new files.
+
+- 0d19345: **Astro Image Service bakes mosaic / blur redacts onto the base
+  PNG** — Phase 3g of `docs/plans/living-spec-authoring-roadmap.md`
+  (Phase 3 follow-up).
+
+  When a screen's `annotations[]` yaml carries
+  `redact { style: "mosaic" | "blur" }` entries, the renderer now
+  calls `burnRedactions` from `@ingcreators/annot-annotator` on
+  the base PNG before SVG-fragment composition. `style: solid`
+  redacts continue to flow through the existing SVG filled-rect
+  path — avoiding an unnecessary PNG round-trip for the common
+  solid case.
+
+  ### New public surface
+
+  `buildRasterRedactRegionsFromYaml(annotations, boxed) →
+BboxRedactRegion[]` (exported from
+  `@ingcreators/annot-product-docs`) walks `annotations[]` for
+  raster-style redact entries, resolves each cutout to a bbox,
+  and emits regions ready for `burnRedactions`. Match-anchored
+  entries whose `match` doesn't resolve are skipped silently —
+  the drift detector (Phase 3d) surfaces them upstream so the
+  build keeps producing a useful PNG while the snapshot
+  catches up.
+
+  ### `renderAnnotatedScreen` flow
+
+  ```
+  load base PNG bytes
+     ↓
+  read element-tree bboxes
+     ↓
+  walk annotations[] → split into:
+     • raster redacts (mosaic / blur) → burnRedactions(base, regions)
+     • SVG annotations (rect / circle / arrow / text / callout
+       / freehand / solid-redact / focusMask / numberedBadge)
+     ↓
+  compose SVG fragments on top of the (possibly burned) base PNG
+     ↓
+  emit final PNG (flat or editable)
+  ```
+
+  ### `mapRedact` change
+
+  `mapRedact` in `mdx-annotations.ts` now returns `null` for
+  `style: "mosaic" | "blur"` so those entries don't double-bake
+  as a filled rect on top of the already-pixelated bitmap. Solid
+  redacts continue to produce a `BboxRectAnnotation` for the SVG
+  path.
+
+  ### `hadBoundingBoxes` semantics
+
+  The flag flips true when raster redacts resolved through bbox
+  data, even when no SVG annotations composed on top. This
+  matches the flag's intent ("we used the snapshot's bbox data
+  to produce a useful render") — a screen with only a mosaic
+  redact still benefited from the bbox tour.
+
+  ### Caching
+
+  The cache key already includes the annotations-yaml source
+  bytes (Phase 2b), so editing a yaml `style: mosaic` → `style:
+blur` value busts the cached PNG without additional
+  bookkeeping.
+
+  ### Compatibility
+
+  Additive. Existing screens (no `annotations[]`, or
+  `annotations[]` with no raster-style redacts) render
+  byte-identical. mosaic / blur redacts that were parser-accepted
+  in 3f but rendered as solid rects now render as their proper
+  raster effect.
+
+### Patch Changes
+
+- Updated dependencies [6124d59]
+- Updated dependencies [0c7ac26]
+- Updated dependencies [64dc6e8]
+- Updated dependencies [691bec5]
+- Updated dependencies [9697f27]
+- Updated dependencies [266b05a]
+  - @ingcreators/annot-annotator@0.6.0
+  - @ingcreators/annot-core@0.3.0
+  - @ingcreators/annot-playwright@0.4.1
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/annotations-yaml.d.ts

@@ -0,0 +1,291 @@
+import { MatchKey, OverlayIntent } from './types.js';
+/**
+ * Current schema version. Per OQ-01 of the roadmap, future v2 / v3
+ * bumps go through strict version dispatch (the parser refuses
+ * unknown majors); within v1, additive optional fields are allowed
+ * without a version bump.
+ */
+export declare const ANNOTATIONS_YAML_VERSION: 1;
+/**
+ * One numbered-badge overlay entry. Phase 2 supports `numberedBadge`
+ * only; Phase 3 of the roadmap extends `OverlayEntry` (and adds a
+ * sibling `AnnotationSpec`) for the full annotation palette
+ * (`rect` / `arrow` / `text` / `freehand` / `redact` / etc.).
+ *
+ * The shape mirrors the legacy {@link OverlaySpec} from `./types.ts`
+ * minus the inline `body` field — descriptions live in MDX
+ * `<AnnotCallout for="id">body</AnnotCallout>` blocks now, not in
+ * the yaml.
+ */
+export interface OverlayEntry {
+    /**
+     * Stable identifier targeted by `<AnnotCallout for="id">` in MDX.
+     * Author-supplied; the migration CLI (Phase 2d) defaults to
+     * `o1` / `o2` / … in `overlays[]` index order.
+     */
+    id: string;
+    /**
+     * Discriminator — Phase 2 ships `numberedBadge` only. Adding a
+     * new kind here means extending the renderer in `AnnotFigure.astro`
+     * AND the drift validator in `./drift.ts`.
+     */
+    kind: "numberedBadge";
+    /** Match key used to locate the element in the page's ElementTree. */
+    match: MatchKey;
+    /** Optional intent flavour for the rendered callout / border. */
+    intent?: OverlayIntent;
+    /**
+     * Numeric badge label rendered on the image. Author-supplied so
+     * the same yaml renders consistent numbering across re-captures
+     * even if `overlays[]` order changes. Required by the Astro
+     * Image Service today; future kinds may make it optional.
+     */
+    number: number;
+}
+/**
+ * Top-level wire shape for an `.annotations.yaml` file.
+ *
+ * `overlays[]` carries the numbered-badge entries the docs flow
+ * pairs with `<AnnotCallout for="id">` description blocks
+ * (Phase 2). `annotations[]` carries the wider visual palette
+ * (Phase 3 of the roadmap) — entries are pure visual marking
+ * with no MDX description slot; their `id` is self-contained
+ * and is NEVER targeted by `<AnnotCallout for>`.
+ *
+ * Both arrays default to empty when absent. Within v1 the
+ * `annotations[]` extension is additive: pre-Phase-3 files
+ * (no `annotations` key) keep parsing unchanged.
+ *
+ * `meta` is an open string map reserved for downstream tooling
+ * (book grouping, generator IDs, etc.) — readers must ignore
+ * unknown keys.
+ */
+export interface AnnotationsFile {
+    version: typeof ANNOTATIONS_YAML_VERSION;
+    overlays: OverlayEntry[];
+    /**
+     * Phase 3 of `docs/plans/living-spec-authoring-roadmap.md`.
+     * Optional sibling of `overlays[]` carrying the full visual
+     * palette (arrows / rects / text labels / callouts / freehand
+     * strokes / redact rects / focus masks). Each entry composes
+     * onto the annotated PNG but has no MDX `<AnnotCallout>`
+     * counterpart.
+     */
+    annotations?: AnnotationSpec[];
+    /** Optional free-form metadata. Readers ignore unknown keys. */
+    meta?: Record<string, string>;
+}
+/**
+ * Common style fields any annotation kind may carry. Mirrors the
+ * `AnnotationStyle` shape in `@ingcreators/annot-annotator`'s DSL
+ * so the yaml → `BboxAnnotation` mapper (Phase 3c) flows straight
+ * through. Inlined here rather than imported so this Tier A module
+ * stays free of the annotator dependency at parse time.
+ */
+export interface AnnotationStyleFields {
+    /** Semantic colour shorthand. Renderer maps to design-system tokens. */
+    intent?: OverlayIntent;
+    /** CSS stroke colour override (wins over `intent`-derived default). */
+    stroke?: string;
+    /** Stroke width in image pixels. */
+    strokeWidth?: number;
+    /** CSS fill colour override (wins over `intent`-derived default). */
+    fill?: string;
+    /** CSS text-fill colour override. */
+    color?: string;
+}
+/** Axis-aligned bbox in page (image) pixels. */
+export interface AnnotationBBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Point in page (image) pixels. */
+export interface AnnotationPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Where a text label sits relative to its anchor element. The
+ * renderer picks a sensible offset (image-pixel padding) per
+ * position. Default `above`.
+ */
+export type TextAnchorPosition = "above" | "below" | "left" | "right" | "center";
+/**
+ * Outline (or filled) rect that highlights one element, a group of
+ * elements (bbox = union), or a free-coord region.
+ *
+ * Exactly one of `match` / `coversElements` / `bbox` is required;
+ * the parser rejects entries that supply zero or multiple.
+ */
+export interface RectAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "rect";
+    match?: MatchKey;
+    coversElements?: MatchKey[];
+    bbox?: AnnotationBBox;
+}
+/**
+ * Circle centred on an element (radius derived from the element's
+ * bbox half-width) or on a free-coord point.
+ */
+export interface CircleAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "circle";
+    /** Element to centre the circle on. Mutually exclusive with `center`. */
+    match?: MatchKey;
+    /** Free-coord centre. Mutually exclusive with `match`. */
+    center?: AnnotationPoint;
+    /**
+     * Radius in image pixels. Required for the `center` form;
+     * optional override for the `match` form (defaults to half the
+     * element's bbox width).
+     */
+    radius?: number;
+}
+/** Arrow endpoint — either match-anchored or free-coord. */
+export type ArrowEndpoint = {
+    match: MatchKey;
+} | {
+    point: AnnotationPoint;
+};
+/** Arrow between two endpoints. */
+export interface ArrowAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "arrow";
+    from: ArrowEndpoint;
+    to: ArrowEndpoint;
+}
+/**
+ * Text label anchored to an element or placed at a free-coord
+ * point. Exactly one of `anchor` / `at` is required.
+ */
+export interface TextAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "text";
+    text: string;
+    /** Match-anchored. The renderer offsets per `position`. */
+    anchor?: {
+        match: MatchKey;
+        position?: TextAnchorPosition;
+    };
+    /** Free-coord placement. */
+    at?: AnnotationPoint;
+    /** Font size in image pixels. Default `14`. */
+    fontSize?: number;
+}
+/** Callout target — either match-anchored or free-coord. */
+export type CalloutTarget = {
+    match: MatchKey;
+} | {
+    bbox: AnnotationBBox;
+};
+/**
+ * Callout = target outline + caption text + arrow from caption to
+ * target. The caption sits at `at`; the target highlights at
+ * `target` (resolved to a bbox via match or supplied directly).
+ */
+export interface CalloutAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "callout";
+    text: string;
+    target: CalloutTarget;
+    /** Caption text position. Required for now (auto-placement is a future enhancement). */
+    at: AnnotationPoint;
+}
+/**
+ * Free-form path. Always free-coord — UI changes may misalign
+ * it; the editor's drift detector intentionally skips it.
+ */
+export interface FreehandAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "freehand";
+    /** SVG path data — `M` / `L` / `C` / `Q` / `Z` commands. */
+    path: string;
+}
+/**
+ * Style of a redact rect. `solid` paints an opaque rect over the
+ * region; `mosaic` and `blur` are raster transforms applied to
+ * the underlying screenshot bitmap before SVG-fragment
+ * composition (Phase 3 follow-up — see Astro Image Service for
+ * the rendering path).
+ */
+export type RedactAnnotationStyle = "solid" | "mosaic" | "blur";
+/**
+ * Opaque or scrambled rect obscuring content. `solid` renders as
+ * a filled rect via the SVG-fragment path; `mosaic` and `blur`
+ * trigger a raster pre-processing pass in the Astro Image Service
+ * (Phase 3 follow-up — Phase 3a–3d shipped `solid` only).
+ */
+export interface RedactAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "redact";
+    match?: MatchKey;
+    bbox?: AnnotationBBox;
+    /**
+     * Defaults to `solid` at render time when omitted. Phase 3 follow-up
+     * (3f) widened this from the original `"solid"`-only to also
+     * accept `"mosaic"` and `"blur"` — both routed through
+     * `burnRedactions` from `@ingcreators/annot-annotator`.
+     */
+    style?: RedactAnnotationStyle;
+}
+/** Focus-mask cutout — element-anchored (with optional padding) or free-coord bbox. */
+export type FocusMaskCutout = {
+    match: MatchKey;
+    padding?: number;
+} | {
+    bbox: AnnotationBBox;
+};
+/**
+ * Darken everything EXCEPT the cutout region. The cutout draws
+ * crisp; everything outside is dimmed by `dimColor`
+ * (default `rgba(0,0,0,0.5)`).
+ */
+export interface FocusMaskAnnotation extends AnnotationStyleFields {
+    id: string;
+    kind: "focusMask";
+    cutout: FocusMaskCutout;
+    /** CSS colour for the dim layer. Default `rgba(0,0,0,0.5)`. */
+    dimColor?: string;
+}
+/**
+ * Discriminated union across every annotation kind Phase 3
+ * supports. Parser dispatches on `kind`; serializer round-trips
+ * to YAML and back to a byte-equivalent object.
+ */
+export type AnnotationSpec = RectAnnotation | CircleAnnotation | ArrowAnnotation | TextAnnotation | CalloutAnnotation | FreehandAnnotation | RedactAnnotation | FocusMaskAnnotation;
+/** The `kind` literal type. */
+export type AnnotationKind = AnnotationSpec["kind"];
+/** Set of every supported `kind`. Reused by the parser + drift detector. */
+export declare const ANNOTATION_KINDS: readonly AnnotationKind[];
+/**
+ * Error thrown when a YAML payload cannot be parsed into the
+ * documented schema. Carries the offending source so callers can
+ * surface line / column context (the CLI prefixes path + heading).
+ */
+export declare class AnnotationsYamlError extends Error {
+    readonly source?: string | undefined;
+    constructor(message: string, source?: string | undefined);
+}
+/**
+ * Parse a YAML string into an `AnnotationsFile`. Throws
+ * {@link AnnotationsYamlError} on shape violations: missing
+ * `version`, unsupported major, missing required `id` / `kind` /
+ * `match` / `number` on an overlay entry.
+ *
+ * The parser is permissive about optional fields: unknown keys at
+ * any level are dropped silently (forward compat within a major).
+ */
+export declare function parseAnnotationsYaml(source: string): AnnotationsFile;
+/**
+ * Serialize an `AnnotationsFile` back to YAML. Output is
+ * deterministic (`version` → `overlays` → `meta`), suitable for
+ * round-trip + git-diff use.
+ *
+ * The serializer rejects entries that wouldn't round-trip through
+ * `parseAnnotationsYaml` — kind is checked at the type level, but
+ * missing `id` / `match` / `number` at runtime throws.
+ */
+export declare function serializeAnnotationsYaml(file: AnnotationsFile): string;