@ingcreators/annot-product-docs 0.2.0 → 0.4.0

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;

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, {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        order?: number | undefined;
-    }, {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        order?: number | undefined;
-    }>, {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        order?: number | undefined;
-    }, {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        order?: number | undefined;
-    }>>;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    title?: string | undefined;
-    purpose?: string | undefined;
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | undefined;
-        order?: number | undefined;
-    } | undefined;
-}, {
-    id: string;
-    title?: string | undefined;
-    purpose?: string | undefined;
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
-        book?: string | undefined;
-        sheet?: string | undefined;
-        sheets?: Record<string, string> | 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, {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            }, {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            }>>;
-        }, "strict", z.ZodTypeAny, {
-            template?: string | undefined;
-            templateSheets?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }, {
-            template?: string | undefined;
-            templateSheets?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }>>>;
-    }, "strict", z.ZodTypeAny, {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    }, {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: 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?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: string | undefined;
-                reference?: string | undefined;
-            } | undefined;
-        }> | undefined;
-    } | undefined;
-}, {
-    meta?: Record<string, unknown> | undefined;
-    xlsx?: {
-        defaultBook?: string | undefined;
-        books?: Record<string, {
-            template?: string | undefined;
-            templateSheets?: {
-                cover?: string | undefined;
-                history?: string | undefined;
-                list?: string | undefined;
-                screen?: 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[];