@ingcreators/annot-product-docs 0.1.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/mdx.d.ts

@@ -0,0 +1,41 @@
+import { ParsedMdx } from './types.js';
+/**
+ * Parse one MDX file from disk. Returns `null` if the file lacks
+ * an `annot:` frontmatter block (regular MDX files in customer
+ * docs sites pass through untouched).
+ */
+export declare function parseMdxFile(filePath: string): Promise<ParsedMdx | null>;
+export interface ParseMdxOptions {
+    /** Used only for error messages; defaults to `<inline>`. */
+    filePath?: string;
+}
+/**
+ * Parse an MDX source string. Returns `null` for sources without
+ * an `annot:` frontmatter block.
+ *
+ * Throws if the `annot:` block exists but fails Zod validation —
+ * typos in `id` / `xlsx.role` etc. should fail loudly rather than
+ * silently dropping content from the output.
+ */
+export declare function parseMdx(source: string, options?: ParseMdxOptions): ParsedMdx | null;
+/**
+ * Rewrite the `annot:snapshot` / `annot:attributes` MDX comment
+ * blocks in a source string in-place, returning a new source
+ * string with the updates applied.
+ *
+ * Used by the Playwright `screen` fixture (PR 3) to keep each
+ * MDX file's snapshot/attribute documentation in sync with what
+ * the live page actually exposes. Pure string transform — does
+ * NOT re-parse / re-stringify the full MDX tree, so authored
+ * Markdown / JSX / whitespace is byte-stable for the unchanged
+ * regions.
+ *
+ * If a block is absent and an update value is provided, the
+ * block is appended at end of file. If a block exists and the
+ * update value is `undefined`, the block is left untouched —
+ * pass an empty string to clear an existing block.
+ */
+export declare function updateCommentBlocks(source: string, updates: {
+    snapshot?: string;
+    attributes?: string;
+}): 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/dist/resolver.d.ts

@@ -0,0 +1,58 @@
+import { Locator, Page } from '@playwright/test';
+import { MatchKey, OverlaySpec } from './types.js';
+export interface SnapshotEntry {
+    role: string;
+    name: string;
+    ref: string;
+    depth: number;
+    /** Parent chain at parse time, oldest ancestor first. Used by `under`. */
+    ancestors: Array<{
+        role: string;
+        name: string;
+    }>;
+}
+export type ResolveResult = {
+    ok: true;
+    locator: Locator;
+    entry: SnapshotEntry;
+} | {
+    ok: false;
+    kind: ResolveFailureKind;
+    reason: string;
+    suggestion?: string;
+    candidates?: string[];
+};
+export type ResolveFailureKind = "not-found" | "ambiguous" | "live-mismatch" | "renamed" | "role-changed";
+/**
+ * Parse the YAML-ish aria-snapshot output from
+ * `page.locator('body').ariaSnapshot({ mode: 'ai' })` into a
+ * flat list of entries with parent-chain context.
+ *
+ * Playwright emits a 2-space-per-level indented bullet list:
+ *
+ *   - dialog "Confirm":
+ *     - button "OK" [ref=e12]
+ *     - button "Cancel" [ref=e13]
+ *
+ * Each line is `- <role> "<name>" [ref=eN]` optionally followed
+ * by `:` (for containers). We walk the lines once, maintaining a
+ * parent stack so each entry knows its full ancestor chain — the
+ * resolver uses that chain to honour `match.under` for
+ * disambiguation.
+ */
+export declare function parseSnapshot(yaml: string): SnapshotEntry[];
+/**
+ * Resolve a single `MatchKey` against a parsed snapshot + live
+ * `Page`. Honours `match.under` by filtering candidate entries
+ * whose ancestor chain ends with the `under` key.
+ */
+export declare function resolveMatch(match: MatchKey, snapshot: SnapshotEntry[], page: Page): Promise<ResolveResult>;
+/**
+ * Resolve every `<Overlay>` in a screen against the snapshot.
+ * Returns one result per overlay in input order, so the caller
+ * can pair them with the source spans for drift reports.
+ */
+export declare function resolveOverlays(overlays: OverlaySpec[], snapshot: SnapshotEntry[], page: Page): Promise<Array<{
+    overlay: OverlaySpec;
+    result: ResolveResult;
+}>>;

package/dist/types-config.d.ts

@@ -0,0 +1,18 @@
+export type { AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, } from './types.js';
+export interface BookConfig {
+    template?: string;
+    templateSheets?: {
+        cover?: string;
+        history?: string;
+        list?: string;
+        screen?: string;
+        reference?: string;
+    };
+}
+export interface AnnotDocsConfig {
+    meta?: Record<string, unknown>;
+    xlsx?: {
+        defaultBook?: string;
+        books?: Record<string, BookConfig>;
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Persistent match key — `role + name` pair, optionally
+ * constrained by a parent `under` key to disambiguate
+ * non-unique role+name combinations.
+ *
+ * Critical: `match` keys NEVER persist Playwright `ref=eN` ids —
+ * those are session-local and change between snapshots. The
+ * resolver walks the live snapshot to find the matching element
+ * each run.
+ */
+export interface MatchKey {
+    role: string;
+    name: string;
+    under?: MatchKey;
+}
+export type OverlayIntent = "info" | "warning" | "error" | "success" | "neutral" | "required" | "action";
+export interface OverlaySpec {
+    match: MatchKey;
+    intent?: OverlayIntent;
+    number?: number;
+    /** Markdown body between the `<Overlay>` opening and closing tags. */
+    body: string;
+}
+export interface TransitionSpec {
+    trigger: MatchKey;
+    on?: string;
+    to?: string;
+    body: string;
+}
+export interface ScreenSpec {
+    id: string;
+    src?: string;
+    overlays: OverlaySpec[];
+}
+export interface HistoryEntrySpec {
+    version: string;
+    date: string;
+    author: string;
+    body: string;
+}
+export interface ScreenListSpec {
+    book?: string;
+    sort?: "byId" | "byOrder" | "byFilePath";
+}
+export type AnnotFrontmatterRole = "cover" | "history" | "list" | "screen" | "reference";
+export interface AnnotXlsxConfig {
+    book?: string;
+    /** Single sheet name — used when the MDX contributes one sheet. */
+    sheet?: string;
+    /** Per-`<Screen>` sheet names — used when the MDX contributes multiple sheets. */
+    sheets?: Record<string, string>;
+    role?: AnnotFrontmatterRole;
+    order?: number;
+}
+export interface AnnotMeta {
+    author?: string;
+    createdDate?: string;
+    revisedDate?: string;
+    revision?: string;
+    reviewedBy?: string;
+    [key: string]: unknown;
+}
+export interface AnnotFrontmatter {
+    id: string;
+    title?: string;
+    purpose?: string;
+    meta?: AnnotMeta;
+    xlsx?: AnnotXlsxConfig;
+}
+/**
+ * Aria-snapshot and HTML-attribute blocks that live as MDX
+ * comments in the body. The Playwright `screen` fixture (PR 3)
+ * writes these in-place after each run so the file's "what the
+ * page looks like" stays accurate alongside the human-authored
+ * `<Overlay>` prose.
+ *
+ * Stored verbatim as the inner text between the open / close
+ * markers — the resolver parses snapshot YAML separately via
+ * `parseSnapshot` in `./resolver.ts`.
+ */
+export interface AnnotCommentBlocks {
+    /** Raw YAML between `{/* annot:snapshot *‌/}` markers. */
+    snapshot?: string;
+    /** Raw text between `{/* annot:attributes *‌/}` markers. */
+    attributes?: string;
+}
+/**
+ * The full extraction result for one MDX file. `frontmatter`
+ * is the `annot:` block; `screens` / `transitions` / `history`
+ * are the JSX components found in the body; `commentBlocks`
+ * captures the MDX comment blocks the fixture rewrites.
+ *
+ * Files without an `annot:` frontmatter block are not parsed —
+ * `parseMdx` returns `null` for them so the CLI can `glob` for
+ * every `*.mdx` and ignore non-annot files cheaply.
+ */
+export interface ParsedMdx {
+    frontmatter: AnnotFrontmatter;
+    screens: ScreenSpec[];
+    transitions: TransitionSpec[];
+    history: HistoryEntrySpec[];
+    screenLists: ScreenListSpec[];
+    commentBlocks: AnnotCommentBlocks;
+    /** Original source text — needed by `serialiseUpdate` for byte-stable rewrites. */
+    source: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs",
-  "version": "0.1.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",
@@ -21,7 +21,7 @@
     "docs",
     "documentation",
     "screen-spec",
-    "画面設計書",
+    "screen-specifications",
     "drift",
     "aria-snapshot"
   ],
@@ -52,8 +52,8 @@
     "@types/mdast": "^4.0.4",
     "@types/unist": "^3.0.3",
     "typescript": "^6.0.3",
-    "vite": "^6.4.2",
-    "vite-plugin-dts": "^5.0.0"
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
     "js-yaml": "^4.1.1",
@@ -65,8 +65,8 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "zod": "^3.25.0",
-    "@ingcreators/annot-annotator": "0.3.0",
-    "@ingcreators/annot-playwright": "0.3.0"
+    "@ingcreators/annot-annotator": "0.5.0",
+    "@ingcreators/annot-playwright": "0.4.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"