@ingcreators/annot-product-docs 0.2.0 → 0.4.0

package/dist/mdx-annotations.d.ts

@@ -0,0 +1,162 @@
+import { BboxAnnotation, BboxNumberedBadgeAnnotation, BboxRedactRegion } from '@ingcreators/annot-annotator';
+import { ElementTree } from '@ingcreators/annot-core';
+import { AnnotationSpec, OverlayEntry } from './annotations-yaml.js';
+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[];
+/**
+ * Convert an `ElementTree` (Phase 1a of
+ * `docs/plans/living-spec-authoring-roadmap.md`) into the same
+ * `BoxedEntry[]` shape `parseSnapshotBoxes` emits, so the Astro
+ * Image Service + Playwright screenshot hook can resolve
+ * `<Overlay match>` against PNG XMP-stored trees with no
+ * additional code path.
+ *
+ * Only nodes with both `name` and `bbox` populated produce
+ * entries — matches the legacy YAML parser's filter (boxed +
+ * referenced entries with a name). Decorative containers and
+ * synthetic roots are skipped.
+ *
+ * Phase 1h of the roadmap. Lives alongside `parseSnapshotBoxes`
+ * so consumers that prefer one input shape don't need to know
+ * about the other.
+ */
+export declare function elementTreeToBoxedEntries(tree: ElementTree): 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[];
+/**
+ * Sibling of {@link buildBadgeAnnotations} that takes yaml-form
+ * {@link OverlayEntry} objects. Phase 2b of
+ * `docs/plans/living-spec-authoring-roadmap.md` — the Image Service
+ * resolves a `<Screen annotations="…">` block against this entry
+ * point instead of the legacy inline `<Overlay>` path.
+ *
+ * Entries without a matching boxed entry are skipped silently —
+ * the drift detector (Phase 2c) surfaces them as findings upstream.
+ */
+export declare function buildBadgeAnnotationsFromYaml(overlays: readonly OverlayEntry[], 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;
+/**
+ * Phase 3c of `docs/plans/living-spec-authoring-roadmap.md`.
+ * Resolve each Phase 3a `AnnotationSpec` against the page's
+ * boxed entries + image dimensions and convert to the
+ * `BboxAnnotation` shape `bboxAnnotationsToSvg` consumes.
+ *
+ * Skips entries whose required `match` (or the matches inside
+ * `coversElements` / `from` / `to` / `target` / `cutout`) can't
+ * be resolved — the drift detector (Phase 3d) surfaces those
+ * upstream. Free-coord entries (`bbox` / `point` / `at` / `path`
+ * / `center`) always resolve.
+ */
+export declare function buildShapeAnnotationsFromYaml(annotations: readonly AnnotationSpec[], boxed: readonly BoxedEntry[], dims: {
+    width: number;
+    height: number;
+}): BboxAnnotation[];
+/**
+ * Phase 3g of `docs/plans/living-spec-authoring-roadmap.md`
+ * (Phase 3 follow-up). Walk `annotations[]` for `redact` entries
+ * whose `style` is a raster transform (`mosaic` / `blur`),
+ * resolve each cutout to a bbox, and emit `BboxRedactRegion[]`
+ * ready for `burnRedactions` from `@ingcreators/annot-annotator`.
+ *
+ * Entries with `style: solid` (or undefined / unset) are skipped
+ * here — the SVG-fragment path
+ * ({@link buildShapeAnnotationsFromYaml}) handles those as
+ * filled rects. Match-anchored entries whose `match` doesn't
+ * resolve are skipped silently (drift detector surfaces them
+ * upstream).
+ *
+ * Returns the regions in document order; `burnRedactions`
+ * applies them in that order with later regions overlaying
+ * earlier ones (no alpha-blending), so authors can express
+ * "mosaic, then opaque overlay on top" combinations by
+ * sequencing entries.
+ */
+export declare function buildRasterRedactRegionsFromYaml(annotations: readonly AnnotationSpec[], boxed: readonly BoxedEntry[]): BboxRedactRegion[];
+/**
+ * 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/migrate-overlays-to-annotations.d.ts

@@ -0,0 +1,49 @@
+import { AnnotationsFile } from './annotations-yaml.js';
+import { OverlaySpec } from './types.js';
+/** Per-file result. The CLI prints a summary across these. */
+export interface OverlayMigrationFileResult {
+    /** Absolute MDX path. */
+    mdxPath: string;
+    /** Per-screen results, in MDX document order. */
+    screens: ScreenOverlayMigrationResult[];
+    /** True when the MDX source was rewritten. */
+    mdxRewritten: boolean;
+}
+export interface ScreenOverlayMigrationResult {
+    /** `<Screen id>` value. */
+    id: string;
+    /** Absolute path of the yaml file (set even on dry-run). */
+    yamlPath?: string;
+    /** True when the yaml was written to disk. */
+    yamlWritten: boolean;
+    /** Number of overlays migrated for this screen. */
+    overlayCount: number;
+    /** Reason for skipping — `"no-overlays"` when the screen has
+     *  zero inline `<Overlay>` children, `"already-migrated"` when
+     *  the `<Screen>` opening tag already carries `annotations`,
+     *  `"no-src"` when `<Screen src>` is missing. */
+    skipReason?: "no-overlays" | "already-migrated" | "no-src";
+}
+export interface MigrateOverlaysOptions {
+    /** When true, doesn't write back to disk — just returns what
+     *  WOULD have been written. Default: false. */
+    dryRun?: boolean;
+    /** Override the function that picks the yaml path. Defaults to
+     *  `<dirname(src)>/<basename(src, '.png')>.annotations.yaml`. */
+    yamlPathFor?: (args: {
+        mdxPath: string;
+        screenId: string;
+        src: string;
+    }) => string;
+}
+/**
+ * Migrate one MDX file. See module-level doc for the
+ * step-by-step.
+ */
+export declare function migrateOverlaysToAnnotationsFile(mdxPath: string, options?: MigrateOverlaysOptions): Promise<OverlayMigrationFileResult>;
+/**
+ * Build the in-memory `AnnotationsFile` for one screen's worth
+ * of inline `<Overlay>` blocks. Exported for unit testing. Pure
+ * data; no IO.
+ */
+export declare function buildAnnotationsFile(overlays: readonly OverlaySpec[]): AnnotationsFile;

package/dist/migrate-to-element-tree.d.ts

@@ -0,0 +1,102 @@
+import { ElementTree } from '@ingcreators/annot-core';
+/**
+ * Result of migrating one MDX file. Returned per file so the CLI
+ * can report a summary; throwers propagate up.
+ */
+export interface MigrationFileResult {
+    /** Absolute path of the MDX file. */
+    mdxPath: string;
+    /** Per-screen results. Same order as `parsed.screens`. */
+    screens: ScreenMigrationResult[];
+    /** True when the MDX source was rewritten (comment blocks
+     *  stripped). False when nothing changed. */
+    mdxRewritten: boolean;
+}
+export interface ScreenMigrationResult {
+    /** `<Screen id>` value. */
+    id: string;
+    /** Absolute path of the PNG that received the XMP write. */
+    pngPath?: string;
+    /** True when an `annot:elementTree` chunk was written. */
+    xmpWritten: boolean;
+    /** Reason for skipping — `"no-snapshot"` when the MDX lacks an
+     *  `annot:snapshot` block, `"no-src"` when `<Screen src>` is
+     *  missing or not a local relative path, `"already-migrated"` when
+     *  the PNG already carried an identical tree. */
+    skipReason?: "no-snapshot" | "no-src" | "already-migrated";
+}
+export interface MigrateOptions {
+    /** When true, doesn't write back to disk — just returns what
+     *  WOULD have been written. Useful for `--dry-run` mode in the
+     *  CLI. Default: false. */
+    dryRun?: boolean;
+    /** Override for the legacy attribute-collection whitelist.
+     *  Defaults to the same `DEFAULT_ATTR_WHITELIST` consumed by
+     *  the productDocs fixture today. */
+    attributeWhitelist?: readonly string[];
+}
+/**
+ * Migrate one MDX file. Reads the file, processes every screen,
+ * writes the updated MDX + per-screen PNG XMP chunks back to disk
+ * (unless `dryRun`). Returns the per-screen result.
+ */
+export declare function migrateMdxFile(mdxPath: string, options?: MigrateOptions): Promise<MigrationFileResult>;
+/**
+ * Build an `ElementTree` from the legacy `annot:snapshot` (Playwright
+ * YAML) and `annot:attributes` (per-overlay attribute dict) blocks.
+ *
+ * Exported separately so tests can exercise the pure conversion
+ * without touching disk.
+ */
+export declare function buildElementTreeFromLegacyBlocks(args: {
+    snapshotYaml: string;
+    attributesYaml: string;
+    whitelist: readonly string[];
+}): ElementTree;
+interface LegacyAttributeEntry {
+    role: string;
+    name: string;
+    attributes: Record<string, string>;
+}
+/**
+ * Parse the legacy `annot:attributes` YAML format:
+ *
+ * ```yaml
+ * button "Sign in":
+ *   type: submit
+ * textbox "Email":
+ *   type: email
+ *   required: ""
+ * ```
+ *
+ * Returns one entry per `role "name":` block with the captured
+ * key / value pairs filtered through `whitelist`. Exported only
+ * for test use.
+ */
+export declare function parseLegacyAttributesYaml(yaml: string, whitelist: readonly string[]): LegacyAttributeEntry[];
+/**
+ * Resolve a `<Screen src>` reference against the MDX file's
+ * directory. Returns `null` for protocol-prefixed URLs (those
+ * can't be a local file the migration can write XMP to).
+ *
+ * Exported for unit tests.
+ */
+export declare function resolvePngPath(mdxPath: string, src: string): string | null;
+/**
+ * Strip the `annot:snapshot` and `annot:attributes` MDX comment
+ * blocks from `source`. Returns `source` unchanged when neither
+ * block is present.
+ *
+ * The comment-block format we look for is:
+ *
+ * ```mdx
+ * {/* annot:snapshot
+ *   - main: ...
+ * *\/}
+ * ```
+ *
+ * (with `{/* ... *\/}` being the MDX expression-wrapped JS
+ * comment the `mdx.ts` `updateCommentBlocks` writes).
+ */
+export declare function stripLegacyCommentBlocks(source: string): string;
+export {};

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/dist/types-config.d.ts

@@ -9,10 +9,32 @@ export interface BookConfig {
         reference?: string;
     };
 }
+/**
+ * Project-level defaults for `<AnnotEditButton>` embed mode +
+ * cloud URL. Phase 5f of
+ * `docs/plans/living-spec-authoring-roadmap.md`. Per-call props
+ * on the component override these defaults.
+ */
+export interface AnnotEditorConfig {
+    /**
+     * Default embed mode for every `<AnnotEditButton>` in the
+     * project. Per-call `mode` prop wins when set. Default
+     * `"newTab"` (per OQ-09's analysis).
+     */
+    embedMode?: "newTab" | "inline" | "disabled";
+    /**
+     * Default cloud editor origin (e.g. `"https://annot.work"`
+     * for the hosted instance, `"https://annot.internal.example.com"`
+     * for an on-prem deployment). Per-call `cloudUrl` prop wins
+     * when set. Default `"https://annot.work"`.
+     */
+    cloudUrl?: string;
+}
 export interface AnnotDocsConfig {
     meta?: Record<string, unknown>;
     xlsx?: {
         defaultBook?: string;
         books?: Record<string, BookConfig>;
     };
+    editor?: AnnotEditorConfig;
 }

package/dist/types.d.ts

@@ -14,6 +14,14 @@ export interface MatchKey {
     under?: MatchKey;
 }
 export type OverlayIntent = "info" | "warning" | "error" | "success" | "neutral" | "required" | "action";
+/**
+ * @deprecated Phase 2e of
+ * `docs/plans/living-spec-authoring-roadmap.md`. The inline
+ * `<Overlay match intent number>body</Overlay>` form is being
+ * replaced by the Phase 2b yaml + `<AnnotCallout for>` shape.
+ * Migrate with `annot docs migrate-overlays-to-annotations`.
+ * Slated for removal per OQ-08 (~2-3 release cycles after 2e).
+ */
 export interface OverlaySpec {
     match: MatchKey;
     intent?: OverlayIntent;
@@ -21,6 +29,21 @@ export interface OverlaySpec {
     /** Markdown body between the `<Overlay>` opening and closing tags. */
     body: string;
 }
+/**
+ * Phase 2b of `docs/plans/living-spec-authoring-roadmap.md`.
+ * A `<AnnotCallout for="id">body</AnnotCallout>` child of a
+ * `<Screen annotations="...">` block. The visible / numbered /
+ * intent-colored callout is composed onto the annotated PNG by the
+ * Image Service using the matching entry in the annotation yaml;
+ * this spec carries only what the MDX side contributes: the
+ * `for=` reference and the inner markdown body.
+ */
+export interface AnnotCalloutSpec {
+    /** References `overlays[].id` in the screen's annotation yaml. */
+    for: string;
+    /** Markdown body between the opening and closing tags. */
+    body: string;
+}
 export interface TransitionSpec {
     trigger: MatchKey;
     on?: string;
@@ -30,7 +53,29 @@ export interface TransitionSpec {
 export interface ScreenSpec {
     id: string;
     src?: string;
+    /**
+     * Legacy inline overlays — `<Overlay>` JSX children of the
+     * `<Screen>` block. Carries match / intent / number / body
+     * inline; deprecated in favour of the Phase 2b annotation yaml
+     * path. Empty when the author has migrated to the yaml form.
+     */
     overlays: OverlaySpec[];
+    /**
+     * Phase 2b of `docs/plans/living-spec-authoring-roadmap.md`.
+     * Optional path (relative to the MDX file) to an
+     * `.annotations.yaml` that describes the screen's overlays —
+     * see `@ingcreators/annot-product-docs/annotations-yaml`. When
+     * set, the Image Service prefers yaml-driven badge composition
+     * over the inline `overlays[]`.
+     */
+    annotations?: string;
+    /**
+     * Phase 2b. `<AnnotCallout for="id">body</AnnotCallout>` JSX
+     * children of the screen, paired with yaml overlay entries by
+     * `id`. Empty when the screen still uses the legacy
+     * `<Overlay>` form.
+     */
+    callouts: AnnotCalloutSpec[];
 }
 export interface HistoryEntrySpec {
     version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -32,6 +32,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./annotations-yaml": {
+      "types": "./dist/annotations-yaml.d.ts",
+      "default": "./dist/annotations-yaml.js"
     }
   },
   "bin": {
@@ -47,26 +51,27 @@
     "access": "public"
   },
   "devDependencies": {
-    "@playwright/test": "^1.50.0",
+    "@playwright/test": "^1.61.1",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
     "@types/unist": "^3.0.3",
     "typescript": "^6.0.3",
-    "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.1"
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.3"
   },
   "dependencies": {
     "js-yaml": "^4.1.1",
+    "playwright-core": "^1.61.1",
     "remark-frontmatter": "^5.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
-    "playwright-core": "^1.50.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
-    "zod": "^3.25.0",
-    "@ingcreators/annot-annotator": "0.5.0",
-    "@ingcreators/annot-playwright": "0.3.1"
+    "zod": "^4.4.3",
+    "@ingcreators/annot-annotator": "0.6.0",
+    "@ingcreators/annot-core": "0.3.0",
+    "@ingcreators/annot-playwright": "0.4.1"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"