@ingcreators/annot-product-docs 0.3.0 → 0.4.1

package/dist/config.d.ts

@@ -5,62 +5,20 @@ export declare const annotFrontmatterSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     purpose: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    xlsx: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+    xlsx: z.ZodOptional<z.ZodObject<{
         book: z.ZodOptional<z.ZodString>;
         sheet: z.ZodOptional<z.ZodString>;
         sheets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        role: z.ZodOptional<z.ZodEnum<["cover", "history", "list", "screen", "reference"]>>;
+        role: z.ZodOptional<z.ZodEnum<{
+            screen: "screen";
+            cover: "cover";
+            history: "history";
+            list: "list";
+            reference: "reference";
+        }>>;
         order: z.ZodOptional<z.ZodNumber>;
-    }, "strict", z.ZodTypeAny, {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    }, {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    }>, {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    }, {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    }>>;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    title?: string | undefined;
-    purpose?: string | undefined;
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    } | undefined;
-}, {
-    id: string;
-    title?: string | undefined;
-    purpose?: string | undefined;
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        role?: "screen" | "cover" | "history" | "list" | "reference" | undefined;
-        order?: number | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const annotDocsConfigSchema: z.ZodObject<{
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     xlsx: z.ZodOptional<z.ZodObject<{
@@ -73,94 +31,18 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
                 list: z.ZodOptional<z.ZodString>;
                 screen: z.ZodOptional<z.ZodString>;
                 reference: z.ZodOptional<z.ZodString>;
-            }, "strict", z.ZodTypeAny, {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            }, {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            }>>;
-        }, "strict", z.ZodTypeAny, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }>>>;
-    }, "strict", z.ZodTypeAny, {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    }, {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    }>>;
-}, "strict", z.ZodTypeAny, {
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    } | undefined;
-}, {
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                screen?: string | undefined;
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    } | undefined;
-}>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    editor: z.ZodOptional<z.ZodObject<{
+        embedMode: z.ZodOptional<z.ZodEnum<{
+            newTab: "newTab";
+            inline: "inline";
+            disabled: "disabled";
+        }>>;
+        cloudUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /**
  * Identity-with-validation helper.
  *
@@ -171,7 +53,7 @@ export declare const annotDocsConfigSchema: z.ZodObject<{
  * dropped by `tsc`'s structural matching.
  */
 export declare function defineConfig(config: AnnotDocsConfig): AnnotDocsConfig;
-export type { AnnotDocsConfig, AnnotFrontmatter, BookConfig, } from './types-config.js';
+export type { AnnotDocsConfig, AnnotEditorConfig, AnnotFrontmatter, BookConfig, } from './types-config.js';
 /**
  * Convenience guard: does this AnnotFrontmatter declare a
  * `screen` role? Useful for filtering MDXs that have `<Screen>`

package/dist/deprecation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Soft-deprecation shim for the legacy inline `<Overlay>` JSX
+ * form. Phase 2e of `docs/plans/living-spec-authoring-roadmap.md`.
+ *
+ * Policy (per OQ-08 of the roadmap):
+ *
+ * - Phase 2e (this module) — Build / lint paths emit a deduped
+ *   warning when they encounter a `<Screen>` block whose overlays
+ *   live inline as `<Overlay>` children rather than yaml + AnnotCallout.
+ *   The warning points at `annot docs migrate-overlays-to-annotations`
+ *   so authors can fix it with one command.
+ *
+ * - Removal target: ~3 months / 2-3 release cycles after Phase 2e
+ *   lands, tracked in [the roadmap](../../../docs/plans/living-spec-authoring-roadmap.md)
+ *   timeline. Removal is its own PR that deletes:
+ *     - `OverlaySpec` from `./types.ts`
+ *     - `Overlay.astro` from `@ingcreators/annot-product-docs-astro`
+ *     - The inline-`<Overlay>` walker branch in `./mdx.ts`
+ *     - The legacy path in `renderAnnotatedScreen` (yaml becomes
+ *       the only renderer input)
+ *
+ * Until then, both forms work. The warning is `console.warn`-only
+ * — it doesn't fail the build by default (CI gating happens at
+ * `annot docs lint --ci`, not at Astro build time).
+ */
+export interface LegacyOverlayUsage {
+    /** Absolute MDX path (or any stable identifier the caller has). */
+    mdxPath: string;
+    /** `<Screen id>` of the block using the legacy form. */
+    screenId: string;
+    /** Number of `<Overlay>` children seen on the screen. */
+    overlayCount: number;
+}
+/**
+ * Emit the deprecation warning. No-op when the same
+ * `(mdxPath, screenId)` pair has already warned in this process.
+ *
+ * The caller (Astro Image Service, lint CLI) decides WHEN to
+ * call this — typically when it sees `screen.overlays.length > 0
+ * && screen.annotations === undefined`.
+ *
+ * @param emit  Optional warning emitter. Defaults to `console.warn`
+ *              so the message lands on whichever transport the
+ *              host already wires up (Astro logs / CLI stderr / etc.).
+ *              Tests inject a spy.
+ */
+export declare function warnLegacyOverlay(usage: LegacyOverlayUsage, emit?: (line: string) => void): void;
+/**
+ * Render the warning message. Exported so tests + bespoke
+ * formatters (CI / GitHub Annotations / etc.) can drive it
+ * without going through `console.warn`.
+ */
+export declare function formatLegacyOverlayWarning(usage: LegacyOverlayUsage): string;
+/**
+ * Test-only: reset the per-process dedup cache. Lets tests
+ * exercise the dedup path with a clean slate.
+ */
+export declare function _resetLegacyOverlayDedupForTests(): void;

package/dist/drift.d.ts

@@ -1,7 +1,9 @@
+import { ElementTree } from '@ingcreators/annot-core';
+import { AnnotationSpec, OverlayEntry } from './annotations-yaml.js';
 import { SnapshotEntry } from './resolver.js';
 import { MatchKey, ScreenSpec } from './types.js';
 export type DriftSeverity = "error" | "warning" | "info";
-export type DriftKind = "added" | "removed" | "renamed" | "role-changed" | "duplicated" | "attribute-drift";
+export type DriftKind = "added" | "removed" | "renamed" | "role-changed" | "duplicated" | "attribute-drift" | "description-missing" | "description-orphan";
 export interface DriftFinding {
     severity: DriftSeverity;
     kind: DriftKind;
@@ -25,6 +27,43 @@ export interface DetectDriftOptions {
     storedAttributesYaml?: string;
     /** Optional verbatim YAML of the freshly-captured attributes. */
     freshAttributesYaml?: string;
+    /**
+     * Phase 2c of `docs/plans/living-spec-authoring-roadmap.md`.
+     * When the screen carries `annotations="…"`, callers parse the
+     * yaml and pass its overlays here. The detector then:
+     *   - Pulls match keys from this list instead of
+     *     `screen.overlays` for the match-cycle (removed / renamed /
+     *     role-changed / duplicated / added).
+     *   - Emits new cross-ref findings: `description-missing` (yaml
+     *     id has no `<AnnotCallout for>`) and `description-orphan`
+     *     (`<AnnotCallout for>` references a yaml id that doesn't
+     *     exist).
+     * Independent of `screen.overlays`: the legacy inline path stays
+     * inert when this is set.
+     */
+    yamlOverlays?: readonly OverlayEntry[];
+    /**
+     * Phase 3d of `docs/plans/living-spec-authoring-roadmap.md`.
+     * Optional sibling to {@link yamlOverlays} for the Phase 3
+     * `annotations[]` palette (rect / circle / arrow / text /
+     * callout / freehand / redact / focusMask). The detector walks
+     * the match keys reachable from each variant via
+     * {@link collectMatchKeysFromAnnotation} and feeds them through
+     * the same match-cycle as the overlays (`removed` / `renamed` /
+     * `role-changed` / `duplicated`). Free-coord entries
+     * (`bbox` / `point` / `at` / `path` / `center`) contribute zero
+     * match keys and are silently skipped.
+     *
+     * `annotations[]` IDs are NEVER referenced from `<AnnotCallout for>`
+     * — they're self-contained visual marking — so no
+     * `description-missing` / `description-orphan` findings fire for
+     * this source.
+     *
+     * Findings from this source attach a `match` derived from the
+     * annotation entry so authors can trace which annotation's match
+     * key triggered the finding.
+     */
+    yamlAnnotations?: readonly AnnotationSpec[];
 }
 /**
  * Compute the drift findings for one `<Screen>` block.
@@ -53,6 +92,45 @@ export declare function detectDriftFromYaml(args: {
     liveSnapshotYaml: string;
     storedAttributesYaml?: string;
     freshAttributesYaml?: string;
+    /** Phase 2c. See {@link DetectDriftOptions.yamlOverlays}. */
+    yamlOverlays?: readonly OverlayEntry[];
+    /** Phase 3d. See {@link DetectDriftOptions.yamlAnnotations}. */
+    yamlAnnotations?: readonly AnnotationSpec[];
+}): DriftFinding[];
+/**
+ * Convert an `ElementTree` (Phase 1a of
+ * `docs/plans/living-spec-authoring-roadmap.md`) into the
+ * `SnapshotEntry[]` shape the drift detector consumes. Pure data
+ * transform — walks the tree depth-first, emits one entry per node
+ * that has both `role` and `name` (decorative containers and
+ * synthetic roots are skipped, matching the legacy parser's filter).
+ *
+ * Phase 1i. Exposed for tests + callers that want to construct
+ * adapters in front of the existing `detectDrift` API without
+ * paying the YAML detour.
+ */
+export declare function elementTreeToSnapshotEntries(tree: ElementTree): SnapshotEntry[];
+/**
+ * Drift detection driven by an `ElementTree` (the canonical
+ * screen-capture model from Phase 1a) instead of the legacy
+ * YAML-parsed `SnapshotEntry[]`. Internally converts the tree
+ * via `elementTreeToSnapshotEntries` and dispatches to
+ * `detectDrift` — both paths produce identical findings for
+ * equivalent inputs.
+ *
+ * Phase 1i. Lets the CLI's `lint` flow consume the new PNG XMP
+ * `annot:elementTree` chunk directly (via `readElementTreePng`)
+ * without round-tripping through Playwright YAML.
+ */
+export declare function detectDriftFromElementTree(args: {
+    screen: ScreenSpec;
+    liveElementTree: ElementTree;
+    storedAttributesYaml?: string;
+    freshAttributesYaml?: string;
+    /** Phase 2c. See {@link DetectDriftOptions.yamlOverlays}. */
+    yamlOverlays?: readonly OverlayEntry[];
+    /** Phase 3d. See {@link DetectDriftOptions.yamlAnnotations}. */
+    yamlAnnotations?: readonly AnnotationSpec[];
 }): DriftFinding[];
 /**
  * Summarise findings by severity. Used by the CLI to decide an
@@ -65,8 +143,10 @@ export declare function summariseDrift(findings: DriftFinding[]): {
 };
 /**
  * A `<Screen>` is drift-checkable when it has at least one
- * `<Overlay>`. Files without `<Screen>` blocks (cover / history /
- * list / reference MDXs) are skipped by the lint walker.
+ * `<Overlay>` (legacy form), an `annotations` ref (yaml form), or
+ * an `<AnnotCallout>` (yaml form, in case the author wrote callouts
+ * before the yaml). Files without `<Screen>` blocks (cover / history
+ * / list / reference MDXs) are skipped by the lint walker.
  */
 export declare function isLintableScreen(screen: ScreenSpec): boolean;
 /**
@@ -75,3 +155,18 @@ export declare function isLintableScreen(screen: ScreenSpec): boolean;
  * "skipped cover.mdx" path cheap.
  */
 export declare function lintableScreens(screens: ScreenSpec[]): ScreenSpec[];
+/**
+ * Walk an `AnnotationSpec` and emit every `MatchKey` reachable
+ * from its match-anchored fields. Free-coord variants
+ * (bbox-only rect / center-only circle / point-only arrow
+ * endpoint / `at`-only text / bbox-only callout target / freehand /
+ * bbox-only redact / bbox-only focusMask cutout) contribute zero
+ * keys.
+ *
+ * Phase 3d of `docs/plans/living-spec-authoring-roadmap.md`.
+ * Exposed publicly so callers (the CLI, alternative drift
+ * detectors, future editor surfaces) can resolve the match keys
+ * a Phase 3a `AnnotationSpec[]` exposes without duplicating the
+ * per-variant traversal.
+ */
+export declare function collectMatchKeysFromAnnotation(spec: AnnotationSpec): MatchKey[];

package/dist/index.d.ts

@@ -1,14 +1,20 @@
+export type { AnnotationBBox, AnnotationKind, AnnotationPoint, AnnotationSpec, AnnotationStyleFields, AnnotationsFile, ArrowAnnotation, ArrowEndpoint, CalloutAnnotation, CalloutTarget, CircleAnnotation, FocusMaskAnnotation, FocusMaskCutout, FreehandAnnotation, OverlayEntry, RectAnnotation, RedactAnnotation, RedactAnnotationStyle, TextAnchorPosition, TextAnnotation, } from './annotations-yaml.js';
+export { ANNOTATION_KINDS, ANNOTATIONS_YAML_VERSION, AnnotationsYamlError, parseAnnotationsYaml, serializeAnnotationsYaml, } from './annotations-yaml.js';
 export { filterAnnotMdxFiles, main, walkMdx, } from './cli.js';
 export { annotDocsConfigSchema, annotFrontmatterSchema, defineConfig, isScreenRole, } from './config.js';
+export type { LegacyOverlayUsage } from './deprecation.js';
+export { _resetLegacyOverlayDedupForTests, formatLegacyOverlayWarning, warnLegacyOverlay, } from './deprecation.js';
 export type { DetectDriftOptions, DriftFinding, DriftKind, DriftSeverity, } from './drift.js';
-export { detectDrift, detectDriftFromYaml, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
+export { collectMatchKeysFromAnnotation, detectDrift, detectDriftFromElementTree, detectDriftFromYaml, elementTreeToSnapshotEntries, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
 export type { ProductDocs, ProductDocsSyncOptions, Screen, ScreenCaptureOptions, } from './fixture.js';
 export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, syncProductDocs, test, } from './fixture.js';
 export type { ParseMdxOptions } from './mdx.js';
 export { parseMdx, parseMdxFile, updateCommentBlocks } from './mdx.js';
 export type { BoxedEntry } from './mdx-annotations.js';
-export { buildBadgeAnnotations, emptyAnnotationsSvg, parseSnapshotBoxes, resolveMdxAnnotations, svgFromBadges, svgFromBboxAnnotations, } from './mdx-annotations.js';
+export { buildBadgeAnnotations, buildBadgeAnnotationsFromYaml, buildRasterRedactRegionsFromYaml, buildShapeAnnotationsFromYaml, elementTreeToBoxedEntries, emptyAnnotationsSvg, parseSnapshotBoxes, resolveMdxAnnotations, svgFromBadges, svgFromBboxAnnotations, } from './mdx-annotations.js';
+export type { MigrateOverlaysOptions, OverlayMigrationFileResult, ScreenOverlayMigrationResult, } from './migrate-overlays-to-annotations.js';
+export { buildAnnotationsFile, migrateOverlaysToAnnotationsFile, } from './migrate-overlays-to-annotations.js';
 export type { ResolveFailureKind, ResolveResult, SnapshotEntry, } from './resolver.js';
 export { parseSnapshot, resolveMatch, resolveOverlays, } from './resolver.js';
-export type { AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
-export type { AnnotDocsConfig, BookConfig } from './types-config.js';
+export type { AnnotCalloutSpec, AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
+export type { AnnotDocsConfig, AnnotEditorConfig, BookConfig } from './types-config.js';