@ingcreators/annot-product-docs-astro 0.1.0 → 0.2.1

package/dist/render.d.ts

@@ -0,0 +1,129 @@
+import { BboxNumberedBadgeAnnotation } from '@ingcreators/annot-annotator';
+import { FileCache } from './cache.js';
+export interface RenderAnnotatedScreenOptions {
+    /** Path to the `.mdx` file (absolute or relative to cwd). */
+    mdxPath: string;
+    /** Must match a `<Screen id="...">` inside the MDX. */
+    screenId: string;
+    /** Optional cache. When supplied, identical inputs short-circuit to a cached buffer. */
+    cache?: FileCache;
+    /** Override the cwd used to resolve relative `mdxPath`. */
+    cwd?: string;
+    /**
+     * Override the base PNG that `<Screen src>` would otherwise
+     * point at. Useful when the on-disk PNG and the served URL
+     * diverge — e.g. an Astro site that serves PNGs from
+     * `public/` while the MDX `<Screen src>` carries the
+     * absolute browser URL. The caller hands in the bytes
+     * directly and `loadBasePng` is skipped.
+     */
+    basePngBytes?: Uint8Array;
+    /**
+     * Emit a re-editable PNG instead of a flat raster. When set,
+     * the visible pixels match the default rasterised output but
+     * the file additionally carries the original (un-annotated)
+     * base image + the annotations SVG in the PNG's XMP metadata
+     * + custom `svGo` chunk, so re-opening the file in Annot Cloud
+     * / the editor / VSCode hosts restores the annotations as
+     * selectable / movable objects.
+     *
+     * Pass `true` for the defaults, or an object to set the optional
+     * `tags` field on the embedded XMP (e.g. `source` / `screen` /
+     * `capturedAt` provenance metadata — see
+     * `@ingcreators/annot-annotator`'s `EditableInput`).
+     *
+     * When no overlay bboxes resolve (the snapshot block has no
+     * `[box=…]` markers yet), the base PNG is wrapped as an editable
+     * PNG with an empty annotations layer — re-opening still works,
+     * the editor just shows the un-annotated capture.
+     */
+    editable?: boolean | {
+        tags?: Record<string, string>;
+    };
+}
+export interface RenderResult {
+    /** Annotated PNG bytes. */
+    bytes: Uint8Array;
+    /** Whether the result came from cache. Useful for logging. */
+    fromCache: boolean;
+    /**
+     * `false` when the source had no bbox markers and we
+     * returned the base PNG verbatim. The Image Service surfaces
+     * this so an Astro plugin can warn the author to run the
+     * Playwright tour.
+     */
+    hadBoundingBoxes: boolean;
+}
+/**
+ * Top-level renderer used by both the Astro Image Service and
+ * vitest test cases. Steps:
+ *
+ *   1. Parse the MDX via `parseMdxFile`.
+ *   2. Find the `<Screen id>` matching `screenId`. Throw with a
+ *      friendly diagnostic if missing.
+ *   3. Compute the cache key from the MDX source + `screenId`.
+ *      On a cache hit, return the bytes immediately.
+ *   4. Load the base PNG referenced by `<Screen src>`.
+ *   5. Parse the stored `annot:snapshot` block for bbox markers.
+ *      If absent, return base PNG verbatim.
+ *   6. Build a typed `BboxCalloutAnnotation[]` from the overlays
+ *      + bbox data, hand it to `createAnnotator().toPng(...)`,
+ *      and return the result.
+ */
+export declare function renderAnnotatedScreen(options: RenderAnnotatedScreenOptions): Promise<RenderResult>;
+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 — the caller falls back to a non-annotated render.
+ */
+export declare function parseSnapshotBoxes(yaml: string): BoxedEntry[];
+/**
+ * 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()`.
+ *
+ * Exposed so the Playwright fixture can compose MDX-derived overlays
+ * with caller-supplied inline overlays before rasterisation. 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 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: import('@ingcreators/annot-annotator').BboxAnnotation[]): string;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs-astro",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Astro integration for `@ingcreators/annot-product-docs`. Wires the MDX components (`<Screen>` / `<Overlay>` / `<Transition>` / `<HistoryEntry>` / `<ScreenList>` / `<TransitionGraph>`) into an Astro site and supplies the Image Service that renders annotated PNGs from `<Screen>` blocks at build time. Phase 2 of docs/plans/living-product-docs.md.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -22,7 +22,7 @@
     "docs",
     "documentation",
     "screen-spec",
-    "画面設計書",
+    "screen-specifications",
     "image-service"
   ],
   "type": "module",
@@ -33,6 +33,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "default": "./dist/playwright/index.js"
+    },
     "./components/Screen.astro": "./dist/components/Screen.astro",
     "./components/Overlay.astro": "./dist/components/Overlay.astro",
     "./components/Transition.astro": "./dist/components/Transition.astro",
@@ -50,17 +54,25 @@
     "access": "public"
   },
   "devDependencies": {
-    "astro": "^5.0.0",
+    "@playwright/test": "^1.50.0",
+    "astro": "^6.3.6",
     "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": {
-    "@ingcreators/annot-annotator": "0.3.0",
-    "@ingcreators/annot-product-docs": "0.1.0"
+    "@ingcreators/annot-core": "0.2.0",
+    "@ingcreators/annot-annotator": "0.5.0",
+    "@ingcreators/annot-product-docs": "0.2.0"
   },
   "peerDependencies": {
-    "astro": "^5.0.0"
+    "@playwright/test": "^1.42.0",
+    "astro": "^5.0.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "vite build",