@ingcreators/annot-product-docs 0.2.0 → 0.3.0

package/dist/mdx-annotations.d.ts

@@ -0,0 +1,91 @@
+import { BboxAnnotation, BboxNumberedBadgeAnnotation } from '@ingcreators/annot-annotator';
+import { OverlaySpec } from './types.js';
+/** A parsed entry of an aria-snapshot YAML line carrying both a
+ *  `[ref=…]` marker and a `[box=x,y,w,h]` marker. */
+export interface BoxedEntry {
+    role: string;
+    name: string;
+    ref: string;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Parse aria-snapshot YAML for entries that carry both `[ref=…]`
+ * and `[box=x,y,w,h]` markers. `box` is the Playwright addition
+ * available when `ariaSnapshot({ boxes: true })` was passed.
+ *
+ * Exposed for unit testing. Returns an empty array if no entries
+ * have boxes — callers fall back to a non-annotated render.
+ */
+export declare function parseSnapshotBoxes(yaml: string): BoxedEntry[];
+/**
+ * Resolve a screen's `<Overlay match>` blocks against the parsed
+ * `BoxedEntry[]` from its snapshot YAML, emitting typed
+ * `BboxNumberedBadgeAnnotation`s ready for
+ * `createAnnotator().toPng()` / `.toEditablePng()`.
+ *
+ * Overlays with no matching boxed entry are skipped silently —
+ * the drift detector (`detectDrift`) surfaces those upstream.
+ */
+export declare function buildBadgeAnnotations(overlays: readonly OverlaySpec[], boxed: readonly BoxedEntry[], dims: {
+    width: number;
+    height: number;
+}): BboxNumberedBadgeAnnotation[];
+/**
+ * Resolve the `<Overlay>` blocks inside `screenId` against the MDX
+ * file's stored `annot:snapshot` block and return a typed
+ * annotation array ready to feed into
+ * `createAnnotator().toEditablePng()`.
+ *
+ * Used by the Playwright screenshot hook (Tier C) and the Astro
+ * Image Service (Tier B-render). Throws the same diagnostics
+ * `renderAnnotatedScreen` would (no annot frontmatter / no
+ * matching `<Screen id>`).
+ *
+ * Returns an empty array when no `<Overlay>` matches a bbox marker
+ * — e.g. the snapshot was never captured, or `<Overlay match>`
+ * targets an element that's no longer in the page.
+ */
+export declare function resolveMdxAnnotations(opts: {
+    mdxPath: string;
+    screenId: string;
+    dims: {
+        width: number;
+        height: number;
+    };
+    cwd?: string;
+}): Promise<BboxNumberedBadgeAnnotation[]>;
+/**
+ * Wrap a `BboxNumberedBadgeAnnotation[]` (or any compatible badge
+ * subset) into a single-root `<svg>` ready for the annotator's
+ * `annotationsSvg` input.
+ *
+ * Mirrors the more general `svgFromBboxAnnotations` below but
+ * stays specifically typed to the badge shape so the Astro Image
+ * Service's `buildBadgeAnnotations()` output flows in without an
+ * extra cast.
+ */
+export declare function svgFromBadges(badges: BboxNumberedBadgeAnnotation[]): string;
+/**
+ * Wrap a generic `BboxAnnotation[]` (the union DSL accepted by
+ * `@ingcreators/annot-annotator`) into a single-root `<svg>` ready
+ * for the annotator's `annotationsSvg` input. Mirrors `svgFromBadges`
+ * but stays type-permissive — the Playwright fixture's inline
+ * overlays can be any `BboxAnnotation` shape, not just numbered
+ * badges.
+ *
+ * Returns the empty wrapper `<svg/>` when `annotations` is empty —
+ * lets the editor open the file with no annotations layer rather
+ * than throwing.
+ */
+export declare function svgFromBboxAnnotations(annotations: BboxAnnotation[]): string;
+/**
+ * Minimal SVG fragment for the "editable wrap, no overlays" case.
+ * The editor's import path reads `annotationsSvg` from the XMP and
+ * reconstructs an empty annotations layer — fine to be wrapper-only.
+ */
+export declare function emptyAnnotationsSvg(): string;

package/dist/playwright-screenshot-hook.d.ts

@@ -0,0 +1,17 @@
+declare module "@ingcreators/annot-playwright" {
+    interface AnnotScreenshotOptions {
+        /**
+         * Refresh the MDX `annot:snapshot` block and resolve the
+         * `<Screen id>`'s `<Overlay>` blocks into bbox-keyed badge
+         * annotations. The MDX file is rewritten in-place with the
+         * current page's aria-snapshot before overlays resolve, so a
+         * single `page.screenshot({ annot: { mdx } })` call covers the
+         * "refresh + capture + bake + write" pipeline.
+         */
+        mdx?: {
+            id: string;
+            path: string;
+        };
+    }
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Living product docs core — parse `.mdx` files with `annot:` frontmatter, resolve `<Overlay match>` keys against live Playwright `aria-snapshot` trees, run drift detection against the rendered UI, and ship a Playwright `screen` fixture that re-captures + re-syncs MDX snapshot blocks. Tier A (Node-only). Phase 1 of docs/plans/living-product-docs.md.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -66,7 +66,7 @@
     "unist-util-visit": "^5.0.0",
     "zod": "^3.25.0",
     "@ingcreators/annot-annotator": "0.5.0",
-    "@ingcreators/annot-playwright": "0.3.1"
+    "@ingcreators/annot-playwright": "0.4.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"