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

package/CHANGELOG.md

@@ -0,0 +1,271 @@
+# @ingcreators/annot-product-docs-astro
+
+## 0.2.0
+
+### Minor Changes
+
+- 2e92c97: First publish of the living-product-docs package family. Phases
+  1-5 + 7 of `docs/plans/living-product-docs.md` landed across
+  PRs 876-899; this entry flips the three packages from
+  `private: true` to publishable and stamps `0.1.0`.
+
+  ### `@ingcreators/annot-product-docs`
+  - MDX parser (`parseMdx` / `parseMdxFile`) — Remark / unified
+    pipeline that walks `.mdx` files with `annot:` frontmatter
+    and extracts `<Screen>` / `<Overlay>` / `<Transition>` /
+    `<HistoryEntry>` / `<ScreenList>` JSX components.
+  - Match resolver (`parseSnapshot` / `resolveMatch` /
+    `resolveOverlays`) for the Playwright `aria-snapshot`
+    YAML, honouring `match.under` disambiguation and emitting
+    `not-found` / `ambiguous` / `renamed` / `role-changed` /
+    `live-mismatch` diagnostics.
+  - `screen` fixture extending `@ingcreators/annot-playwright`
+    with `screen.capture({ id, mdxPath })` that re-syncs
+    `annot:snapshot` + `annot:attributes` MDX comment blocks
+    in place.
+  - Drift detector (`detectDrift` / `detectDriftFromYaml`) — six
+    finding kinds (added / removed / renamed / role-changed /
+    duplicated / attribute-drift) with severity buckets.
+  - `annot-docs` CLI (`init` / `sync` / `lint`) with `--json`
+    / `--ci` / `--fix` flags + a sample GitHub Actions workflow
+    emitting GitHub annotations on PR diff views.
+
+  ### `@ingcreators/annot-product-docs-astro`
+  - `productDocsIntegration()` Astro 5.x integration factory.
+  - 7 docs components: `<Screen>`, `<Overlay>`, `<Transition>`,
+    `<TransitionTable>`, `<HistoryEntry>`, `<ScreenList>`,
+    `<TransitionGraph>`. Shipped as `.astro` source under
+    `./components/*.astro` exports.
+  - Image Service (`renderAnnotatedScreen` + SHA-keyed
+    `createFileCache` / `createMemoryCache`) that composes the
+    base screenshot with overlay callouts at build time.
+
+  ### `@ingcreators/annot-product-docs-xlsx`
+  - MDX → normalised bundle extractor; per-role default layout
+    (cover / history / list / screen / reference); customer-
+    template support with `{var}` placeholder substitution
+    (including `{annot:date}` special vars + `{name:format}`
+    date formatting); Excel Named Range writers
+    (`annotImage` / `annotItemTable` / `annotHistory` /
+    `annotList` / `annotSnapshot` / `annotAttributes`).
+  - `annot-docs-xlsx render` CLI with multi-book emit + per-book
+    template config.
+
+- 4768855: **`@ingcreators/annot-product-docs-astro` — new `/playwright`
+  subpath** that re-exports an extended Playwright `test` fixture
+  whose `page.screenshot()` accepts a compositional `annot: { … }`
+  option:
+
+  ```ts
+  import { test } from "@ingcreators/annot-product-docs-astro/playwright";
+
+  test("login flow", async ({ page }) => {
+    await page.goto("/login");
+    await page.screenshot({
+      path: "public/login.png",
+      annot: {
+        mdx: { id: "login", path: "src/content/docs/login.mdx" },
+        tags: { source: "docs-tour", capturedAt: new Date().toISOString() },
+      },
+    });
+  });
+  ```
+
+  The `annot` option is compositional — each field is an
+  independent contribution to the embedded XMP record:
+  - `mdx: { id, path }` — refresh the MDX's `annot:snapshot` block
+    against the current page, then resolve `<Overlay match>` blocks
+    for the named `<Screen>`.
+  - `overlays: BboxAnnotation[]` — caller-supplied annotations
+    (same DSL `@ingcreators/annot-annotator` accepts). Merged with
+    MDX-derived overlays when both are present.
+  - `tags: Record<string, string>` — provenance metadata written
+    verbatim into the XMP. No auto-fill — callers write the
+    `WELL_KNOWN_TAG_KEYS` they want.
+  - `editable: boolean` (default `true`) — toggle between
+    "annotations preserved as SVG layer + embedded original"
+    (re-editable in Annot Cloud) and "annotations baked into
+    visible pixels" (flat PNG, no XMP layer).
+
+  `page.screenshot()` calls WITHOUT `annot` fall through to
+  vanilla Playwright byte-for-byte — codegen / DevTools Recorder
+  output keeps working unedited.
+
+  Phase 1 of
+  `docs/plans/playwright-screenshot-annot-fixture.md`. Phase 2 will
+  add the same interception on `locator.screenshot()` with
+  coordinate rebasing for sub-region overlays.
+
+  Two helpers also exported from the main `@ingcreators/annot-product-docs-astro`
+  entry for callers who want to compose annotations themselves:
+  - `resolveMdxAnnotations({ mdxPath, screenId, dims })` — extract
+    the MDX's `<Overlay>` blocks into a typed `BboxNumberedBadgeAnnotation[]`
+    (the underlying step the fixture uses internally).
+  - `svgFromBboxAnnotations(annotations)` — wrap a
+    `BboxAnnotation[]` into a single-root `<svg>` ready for
+    `Annotator.toEditablePng()` / `toPng()`.
+
+  **`@ingcreators/annot-core` — new `writePngWithTagsOnly`
+  helper** exported from `/xmp-bytes` (and re-exported from
+  `/xmp`). Writes `tags` into a PNG's XMP iTXt chunk without
+  embedding an original capture or annotations layer — for the
+  "PNG with provenance metadata sidecar" path (CI failure
+  screenshots, VRT references, etc.). The resulting bytes are
+  still a valid PNG and the Annot editor treats them as a normal
+  PNG (no `<annot:annotations>` element → not editable round-trip;
+  opens as fresh canvas).
+
+- 49b5585: **`locator.screenshot({ annot: { … } })` support** — Phase 2 of
+  `docs/plans/playwright-screenshot-annot-fixture.md`. The fixture
+  now patches `Locator.prototype.screenshot` alongside
+  `Page.prototype.screenshot`, and overlay coordinates are
+  automatically rebased into the cropped image's coordinate space:
+
+  ```ts
+  await page.locator("header").screenshot({
+    path: "header.png",
+    annot: {
+      overlays: [
+        // page-space bbox — rebased onto the header-locator's clip
+        { type: "rect", bbox: { x: 120, y: 60, width: 50, height: 30 } },
+      ],
+    },
+  });
+  ```
+
+  Overlays whose page-space bbox falls outside the locator's
+  bounding box are dropped (warning + skip per Open Question 4)
+  and surfaced via:
+  - `console.warn(...)` to stderr — always
+  - `test.info().annotations` as a `warning` entry when running
+    under Playwright — best-effort, guarded so vitest unit tests
+    don't crash
+
+  `page.screenshot({ clip, annot })` honours `clip` the same way —
+  explicit clip + auto rebase. Mirrors vanilla
+  `page.screenshot({ clip })` semantics; only the overlay-rebase
+  behaviour is annot-specific.
+
+  When the locator has no bounding box (off-screen / hidden), the
+  fixture throws a friendly diagnostic asking the caller to use
+  a stable selector / `waitFor()`.
+
+  **Coordinate-rebase API** — exported alongside the fixture for
+  callers who want to compose annotations themselves:
+
+  ```ts
+  import { rebaseAnnotations } from "@ingcreators/annot-product-docs-astro/playwright";
+  // Or for direct algorithmic use without the fixture:
+  //   import { rebaseAnnotations } from "@ingcreators/annot-product-docs-astro/playwright/rebase";
+
+  const { kept, dropped } = rebaseAnnotations(annotations, clip);
+  ```
+
+  Returns `{ kept, dropped }` for each shape in the
+  `BboxAnnotation` union (rect / numberedBadge / circle / arrow /
+  text / callout). Raw SVG fragments (`type: "raw"`) pass through
+  unchanged — the caller is responsible for emitting clip-space
+  coords inside arbitrary SVG.
+
+  `numberedBadge`'s `imageWidth` / `imageHeight` are also rebased
+  to the clip dimensions so `placement: "auto"` picks the corner
+  against the cropped image edge rather than the page edge.
+
+- 730fab7: `renderAnnotatedScreen()` gains an optional `editable?: boolean |
+{ tags?: Record<string, string> }` field. Pass `true` (or an
+  object) and the function routes through the new
+  `Annotator.toEditablePng()` path: the returned PNG carries the
+  same visible callouts plus the original capture + the
+  annotations SVG embedded in XMP / custom `svGo` chunk, so
+  re-opening the file in the Annot editor / Cloud restores the
+  overlays as selectable / movable / restylable objects rather
+  than a flat bitmap.
+
+  ```ts
+  const result = await renderAnnotatedScreen({
+    mdxPath: "docs/app/index.mdx",
+    screenId: "app-overview",
+    basePngBytes,
+    editable: {
+      tags: {
+        source: "docs-tour",
+        capturedAt: new Date().toISOString(),
+      },
+    },
+  });
+  await writeFile("public/app/shots/app-overview.png", result.bytes);
+  ```
+
+  The cache key folds in the `editable` flag, so flat and editable
+  variants of the same screen don't collide. Existing flat-raster
+  callers are byte-for-byte unaffected — the option defaults to
+  `undefined` (flat).
+
+  The `CacheKeyInput` type gains a parallel `editable?: boolean`
+  field; pure helpers that compute the cache key directly should
+  forward the bit when threading the flag through.
+
+  Internal note: this PR also adds `@ingcreators/annot-core` as a
+  devDependency so tests can import `readEditablePngBytes` from
+  `/xmp-bytes` for round-trip verification. Runtime dependencies
+  are unchanged.
+
+### Patch Changes
+
+- 657a685: **Republish with `dist/` included.** The `0.1.0` tarballs of all
+  three packages shipped to npm without their `dist/` directory —
+  the `publish.yml` workflow's pre-pack `pnpm build` step had only
+  filtered four other packages, so `pnpm pack` packed the three
+  `product-docs*` packages against empty `dist/`s. The
+  `publishConfig.main` (`./dist/index.js`) consequently pointed at
+  a missing file, breaking `npm install` for every consumer.
+
+  The source fix landed in
+  [#947](https://github.com/ingcreators/annot/pull/947) with two
+  defences:
+  1. Three new `--filter` lines in the workflow's build step so
+     all seven publishable packages get built before pack.
+  2. A per-package `prepack` script (`pnpm run build`) so even a
+     misconfigured workflow (or a manual `pnpm pack` / `pnpm
+publish`) refreshes `dist/` before packing.
+
+  No source-code changes in any of the three packages — only the
+  packaging is fixed. This patch publish exists solely to deliver
+  working tarballs to the registry; the public API surface is
+  byte-identical to `0.1.0`.
+
+  Verified locally:
+
+  ```
+  $ pnpm --filter @ingcreators/annot-product-docs pack --dry-run
+  Tarball Contents
+    bin/annot-docs.mjs
+    dist/cli.d.ts
+    dist/config.d.ts
+    dist/drift.d.ts
+    dist/fixture.d.ts
+    dist/index.d.ts
+    dist/index.js
+    dist/mdx.d.ts
+    dist/resolver.d.ts
+    dist/types-config.d.ts
+    dist/types.d.ts
+    LICENSE
+    package.json
+    README.md
+  ```
+
+  Before the fix the same command produced 4 files (LICENSE +
+  README + package.json + bin/annot-docs.mjs), no compiled code.
+
+- Updated dependencies [806badc]
+- Updated dependencies [2e8d397]
+- Updated dependencies [780985d]
+- Updated dependencies [df1a429]
+- Updated dependencies [2e92c97]
+- Updated dependencies [5e74421]
+- Updated dependencies [4768855]
+- Updated dependencies [657a685]
+  - @ingcreators/annot-annotator@0.5.0
+  - @ingcreators/annot-core@0.2.0
+  - @ingcreators/annot-product-docs@0.2.0

package/README.md

@@ -9,7 +9,7 @@ docs-MDX components into an Astro site and ships an Image Service
 that renders annotated PNGs from `<Screen>` blocks at build time.
 
 Phase 2 of
-[`docs/plans/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/living-product-docs.md).
+[`docs/plans/_done/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/_done/living-product-docs.md).
 
 ## Install
 
@@ -89,6 +89,42 @@ When the stored snapshot lacks `[box=x,y,w,h]` markers (no
 Playwright tour has run yet), the function returns the base
 PNG verbatim with `hadBoundingBoxes: false`.
 
+## Playwright fixture (`/playwright` subpath)
+
+For Playwright specs producing screenshots of a documented
+screen, the `./playwright` subpath ships an extended `test`
+fixture that intercepts `page.screenshot()` and
+`locator.screenshot()`. Calls carrying a compositional
+`annot: { mdx | overlays | tags | editable }` option get a
+one-line capture pipeline that replaces the previous
+`page.screenshot` + `screen.capture` + `renderAnnotatedScreen`
++ `writeFile` quartet:
+
+```ts
+import { test } from "@ingcreators/annot-product-docs-astro/playwright";
+
+test("app overview", async ({ page }) => {
+  await page.goto("https://annot.work/app/");
+  await page.screenshot({
+    path: "public/app/shots/app-overview.png",
+    annot: {
+      mdx: { id: "app-overview", path: "src/content/docs/app/index.mdx" },
+      tags: { source: "docs-tour", capturedAt: new Date().toISOString() },
+    },
+  });
+});
+```
+
+Calls without `annot` (or with `annot: true` / `{}`) fall
+through to vanilla Playwright byte-for-byte — codegen-emitted
+calls keep working unedited. See the docs at
+[`annot.work/docs/product-docs/playwright-fixture/`](https://annot.work/docs/product-docs/playwright-fixture/)
+for the compositional vocabulary, locator screenshot semantics,
+and the codegen→hand-edit workflow.
+
+`@playwright/test` is an **optional peer** — Astro-only users
+don't need to install it.
+
 ## Tier
 
 Tier B-render — Astro build-time, no live editor.

package/dist/cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Bumped any time the rendering pipeline changes the bytes it
+ * produces for the same input. Forces a cold cache on every
+ * consumer the next time they build. Keep this small (a single
+ * digit per breaking change) — large jumps don't help and just
+ * obscure the upgrade history.
+ */
+export declare const RENDER_PIPELINE_VERSION = 1;
+export interface CacheKeyInput {
+    mdxSource: string;
+    screenId: string;
+    /**
+     * Whether the render targets a re-editable PNG (vs the default flat
+     * raster). Folded into the cache key so flat / editable variants of
+     * the same screen don't collide. Defaults to `false` to preserve the
+     * historical key shape for flat callers.
+     */
+    editable?: boolean;
+}
+/**
+ * Compute the cache key for a `<Screen>` block. Stable across
+ * runs as long as the MDX source bytes and the screen id are
+ * unchanged.
+ */
+export declare function cacheKey(input: CacheKeyInput): string;
+export interface FileCache {
+    /** Returns the cached bytes for `key`, or `null` on a miss. */
+    get(key: string): Promise<Uint8Array | null>;
+    /** Writes `bytes` under `key`. Overwrites silently. */
+    set(key: string, bytes: Uint8Array): Promise<void>;
+    /** Filesystem path the cache writes into. */
+    readonly dir: string;
+}
+/**
+ * Disk-backed cache rooted at `dir`. The directory is created on
+ * first `set`; reads of nonexistent paths return `null`. Files
+ * are flat (no subdirs), one per key — SHA-256 collisions are
+ * a non-concern given the keyspace.
+ */
+export declare function createFileCache(dir: string): FileCache;
+/**
+ * In-memory cache — useful in tests and as a fallback when the
+ * caller doesn't want disk persistence. Same shape as the disk
+ * cache for swap-in convenience.
+ */
+export declare function createMemoryCache(): FileCache;

package/dist/components/HistoryEntry.astro

@@ -0,0 +1,34 @@
+---
+// `<HistoryEntry>` — single revision-history row.
+//
+// MDX usage (inside a `role: history` doc):
+//   <HistoryEntry version="1.0" date="2026-03-15" author="Alice">
+//     Initial draft, requirements v2.0.
+//   </HistoryEntry>
+//
+// Multiple entries stack vertically; the Excel adapter renders
+// them into the workbook's history sheet via the `annotHistory`
+// named range.
+
+interface Props {
+  version: string;
+  date: string;
+  author?: string;
+}
+const { version, date, author } = Astro.props;
+---
+<div
+  class="annot-history-entry"
+  data-version={version}
+  data-date={date}
+  data-author={author}
+>
+  <div class="annot-history-meta">
+    <span class="annot-history-version">v{version}</span>
+    <time class="annot-history-date" datetime={date}>{date}</time>
+    {author && <span class="annot-history-author">{author}</span>}
+  </div>
+  <div class="annot-history-body">
+    <slot />
+  </div>
+</div>

package/dist/components/Overlay.astro

@@ -0,0 +1,50 @@
+---
+// `<Overlay>` — caption for one numbered callout on a screen.
+//
+// MDX usage:
+//   <Overlay match={{ role: "textbox", name: "Email" }}
+//            intent="required" number={1}>
+//     **Email** — enter your registered email.
+//   </Overlay>
+//
+// Build-time positioning of the visual callout on the
+// screenshot is handled by the Image Service. This component
+// emits the prose body as a `<li>` in a description list
+// alongside the screen — readers see the screenshot + a
+// numbered legend in parallel.
+
+interface Match {
+  role: string;
+  name: string;
+  under?: Match;
+}
+type Intent =
+  | "info"
+  | "warning"
+  | "error"
+  | "success"
+  | "neutral"
+  | "required"
+  | "action";
+
+interface Props {
+  match: Match;
+  intent?: Intent;
+  number?: number;
+}
+const { match, intent, number } = Astro.props;
+---
+<li
+  class="annot-overlay"
+  data-intent={intent}
+  data-overlay-number={number}
+  data-match-role={match.role}
+  data-match-name={match.name}
+>
+  {number !== undefined && (
+    <span class="annot-overlay-number" aria-hidden="true">{number}</span>
+  )}
+  <div class="annot-overlay-body">
+    <slot />
+  </div>
+</li>

package/dist/components/Screen.astro

@@ -0,0 +1,27 @@
+---
+// `<Screen>` — annotated screenshot block.
+//
+// MDX usage:
+//   <Screen id="login" src="./shots/login.png">
+//     <Overlay match={...} number={1}>...</Overlay>
+//   </Screen>
+//
+// The annotated PNG is produced at build time by the Image
+// Service in `@ingcreators/annot-product-docs-astro` (see
+// `../render.ts`). At render time we just emit an `<img>` that
+// points at the cache hash; the Astro pipeline resolves the
+// final URL.
+
+interface Props {
+  id: string;
+  src: string;
+  alt?: string;
+}
+const { id, src, alt } = Astro.props;
+---
+<figure class="annot-screen" data-screen-id={id}>
+  <img src={src} alt={alt ?? `Screen ${id}`} loading="lazy" />
+  <div class="annot-screen-overlays" data-screen-overlays={id}>
+    <slot />
+  </div>
+</figure>

package/dist/components/ScreenList.astro

@@ -0,0 +1,58 @@
+---
+// `<ScreenList>` — auto-enumerated list of every `role: screen`
+// MDX in the same `book`.
+//
+// MDX usage (inside a `role: list` doc):
+//   <ScreenList book="Screen spec" sort="byId" entries={...} />
+//
+// The `entries` prop is normally populated by the Astro
+// integration's `astro:config:setup` walker (Phase 4 polish).
+// Until that's wired up, callers pass `entries` explicitly so
+// the component renders deterministically in tests and in
+// dev-mode-without-build.
+
+export interface ScreenListEntry {
+  id: string;
+  title?: string;
+  href?: string;
+  order?: number;
+}
+
+interface Props {
+  book?: string;
+  sort?: "byId" | "byOrder" | "byFilePath";
+  entries: ScreenListEntry[];
+}
+const { book, sort = "byId", entries } = Astro.props;
+
+const sortedEntries = [...entries].sort((a, b) => {
+  if (sort === "byOrder") {
+    return (a.order ?? 100) - (b.order ?? 100);
+  }
+  // byId / byFilePath both fall back to alphabetical for
+  // determinism.
+  return a.id.localeCompare(b.id);
+});
+---
+<table class="annot-screen-list" data-book={book} data-sort={sort}>
+  <thead>
+    <tr>
+      <th>ID</th>
+      <th>Screen</th>
+    </tr>
+  </thead>
+  <tbody>
+    {sortedEntries.map((entry) => (
+      <tr data-screen-id={entry.id}>
+        <td>{entry.id}</td>
+        <td>
+          {entry.href ? (
+            <a href={entry.href}>{entry.title ?? entry.id}</a>
+          ) : (
+            <span>{entry.title ?? entry.id}</span>
+          )}
+        </td>
+      </tr>
+    ))}
+  </tbody>
+</table>

package/dist/components/Transition.astro

@@ -0,0 +1,48 @@
+---
+// `<Transition>` — describes one screen-to-screen transition.
+//
+// MDX usage:
+//   <Transition
+//     trigger={{ role: "button", name: "Sign in" }}
+//     on="click"
+//     to="dashboard"
+//   >
+//     Successful login redirects to the dashboard.
+//   </Transition>
+//
+// Renders inline as part of the screen's prose; for a tabular
+// list of every transition on the screen, wrap in
+// `<TransitionTable>` instead.
+
+interface Match {
+  role: string;
+  name: string;
+  under?: Match;
+}
+
+interface Props {
+  trigger: Match;
+  on?: string;
+  to?: string;
+}
+const { trigger, on, to } = Astro.props;
+---
+<div
+  class="annot-transition"
+  data-trigger-role={trigger.role}
+  data-trigger-name={trigger.name}
+  data-on={on}
+  data-to={to}
+>
+  <div class="annot-transition-summary">
+    <code class="annot-transition-trigger">{trigger.name}</code>
+    {on && <span class="annot-transition-event">{on}</span>}
+    {to && (
+      <span class="annot-transition-arrow" aria-hidden="true">→</span>
+    )}
+    {to && <code class="annot-transition-target">{to}</code>}
+  </div>
+  <div class="annot-transition-body">
+    <slot />
+  </div>
+</div>

package/dist/components/TransitionGraph.astro

@@ -0,0 +1,46 @@
+---
+// `<TransitionGraph>` — Mermaid-rendered cross-screen graph.
+//
+// MDX usage (typically in a `role: list` doc):
+//   <TransitionGraph entries={...} title="Auth flow" />
+//
+// Emits a `<pre class="mermaid">` block containing a Mermaid
+// flowchart definition. Rendering happens client-side via the
+// Mermaid runtime the consumer adds to their Astro site
+// (`<script type="module" src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs">`),
+// or build-time via Mermaid CLI / `@napi-rs/canvas` if the
+// consumer opts in.
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  label?: string;
+}
+
+interface Props {
+  entries: GraphEdge[];
+  title?: string;
+  direction?: "TB" | "LR" | "BT" | "RL";
+}
+const { entries, title, direction = "TB" } = Astro.props;
+
+const escape = (id: string): string => id.replace(/[^A-Za-z0-9_]/g, "_");
+
+const mermaid = ["flowchart " + direction];
+if (title) {
+  mermaid.push(`%% ${title.replace(/\r?\n/g, " ")}`);
+}
+for (const edge of entries) {
+  const from = escape(edge.from);
+  const to = escape(edge.to);
+  const label = edge.label
+    ? `|${edge.label.replace(/\|/g, "&#124;")}|`
+    : "";
+  mermaid.push(`  ${from}[${edge.from}] -->${label} ${to}[${edge.to}]`);
+}
+const definition = mermaid.join("\n");
+---
+<figure class="annot-transition-graph" data-direction={direction}>
+  {title && <figcaption>{title}</figcaption>}
+  <pre class="mermaid">{definition}</pre>
+</figure>

package/dist/components/TransitionTable.astro

@@ -0,0 +1,55 @@
+---
+// `<TransitionTable>` — tabular list of every `<Transition>`
+// on the page. Pass an array of transition descriptors as the
+// `entries` prop; the table renders them with one row per
+// transition. The reader sees "trigger / event / target" as
+// columns plus a body cell with the prose.
+//
+// MDX usage:
+//   <TransitionTable
+//     entries={[
+//       { trigger: "Sign in", on: "click", to: "dashboard", body: "..." },
+//       { trigger: "Sign up", on: "click", to: "signup", body: "..." },
+//     ]}
+//   />
+//
+// The companion `<Transition>` component is the inline variant
+// for free-flowing prose. Both compile to data attributes the
+// reader CSS can style consistently.
+
+export interface TransitionEntry {
+  trigger: string;
+  on?: string;
+  to?: string;
+  body?: string;
+}
+
+interface Props {
+  entries: TransitionEntry[];
+}
+const { entries } = Astro.props;
+---
+<table class="annot-transition-table">
+  <thead>
+    <tr>
+      <th>Trigger</th>
+      <th>Event</th>
+      <th>Target</th>
+      <th>Notes</th>
+    </tr>
+  </thead>
+  <tbody>
+    {entries.map((entry) => (
+      <tr
+        data-trigger={entry.trigger}
+        data-on={entry.on}
+        data-to={entry.to}
+      >
+        <td>{entry.trigger}</td>
+        <td>{entry.on ?? "—"}</td>
+        <td>{entry.to ?? "—"}</td>
+        <td set:html={entry.body ?? ""} />
+      </tr>
+    ))}
+  </tbody>
+</table>

package/dist/components/types.d.ts

@@ -0,0 +1,21 @@
+import { MatchKey } from '@ingcreators/annot-product-docs';
+export type Match = MatchKey;
+export type OverlayIntent = "info" | "warning" | "error" | "success" | "neutral" | "required" | "action";
+export interface TransitionEntry {
+    trigger: string;
+    on?: string;
+    to?: string;
+    body?: string;
+}
+export interface ScreenListEntry {
+    id: string;
+    title?: string;
+    href?: string;
+    order?: number;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+export type GraphDirection = "TB" | "LR" | "BT" | "RL";

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { CacheKeyInput, FileCache } from './cache.js';
+export { cacheKey, createFileCache, createMemoryCache, RENDER_PIPELINE_VERSION, } from './cache.js';
+export type { GraphDirection, GraphEdge, Match, OverlayIntent, ScreenListEntry, TransitionEntry, } from './components/types.js';
+export type { ProductDocsIntegrationOptions } from './integration.js';
+export { productDocsIntegration } from './integration.js';
+export type { RenderAnnotatedScreenOptions, RenderResult, } from './render.js';
+export { parseSnapshotBoxes, renderAnnotatedScreen, resolveMdxAnnotations, svgFromBboxAnnotations, } from './render.js';

package/dist/index.js

@@ -0,0 +1,180 @@
+import { createHash as e } from "node:crypto";
+import { mkdir as t, readFile as n, writeFile as r } from "node:fs/promises";
+import { dirname as i, isAbsolute as a, join as o, resolve as s } from "node:path";
+import { bboxAnnotationsToSvg as c, createAnnotator as l } from "@ingcreators/annot-annotator";
+import { parseMdxFile as u } from "@ingcreators/annot-product-docs";
+//#region src/cache.ts
+var d = 1;
+function f(t) {
+	let n = e("sha256");
+	return n.update("v1\n"), n.update(t.mdxSource), n.update("\0"), n.update(t.screenId), t.editable && n.update("\0editable"), n.digest("hex");
+}
+function p(e) {
+	return {
+		dir: e,
+		async get(t) {
+			try {
+				let r = await n(o(e, `${t}.png`));
+				return new Uint8Array(r.buffer, r.byteOffset, r.byteLength);
+			} catch (e) {
+				if (e.code === "ENOENT") return null;
+				throw e;
+			}
+		},
+		async set(n, a) {
+			let s = o(e, `${n}.png`);
+			await t(i(s), { recursive: !0 }), await r(s, a);
+		}
+	};
+}
+function m() {
+	let e = /* @__PURE__ */ new Map();
+	return {
+		dir: ":memory:",
+		async get(t) {
+			return e.get(t) ?? null;
+		},
+		async set(t, n) {
+			e.set(t, n);
+		}
+	};
+}
+//#endregion
+//#region src/integration.ts
+var h = "@ingcreators/annot-product-docs-astro";
+function g(e = {}) {
+	let t = {
+		contentDir: e.contentDir ?? "docs",
+		configPath: e.configPath ?? "annot-docs.config.ts",
+		verbose: e.verbose ?? !1
+	};
+	return {
+		name: h,
+		hooks: { "astro:config:setup": ({ logger: e }) => {
+			t.verbose && e.info(`${h} installed — contentDir=${t.contentDir} configPath=${t.configPath}`);
+		} }
+	};
+}
+//#endregion
+//#region src/render.ts
+async function _(e) {
+	let t = e.cwd ?? process.cwd(), n = a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath), r = await u(n);
+	if (!r) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no \`annot:\` frontmatter — cannot render.`);
+	let o = r.screens.find((t) => t.id === e.screenId);
+	if (!o) throw Error(`renderAnnotatedScreen: ${e.mdxPath} has no <Screen id="${e.screenId}"> block.`);
+	let c = v(e.editable), d = f({
+		mdxSource: r.source,
+		screenId: e.screenId,
+		editable: c !== null
+	});
+	if (e.cache) {
+		let t = await e.cache.get(d);
+		if (t) return {
+			bytes: t,
+			fromCache: !0,
+			hadBoundingBoxes: !0
+		};
+	}
+	let p = e.basePngBytes ?? await T(r, o.src, i(n)), m = E(p), h = b(r.commentBlocks.snapshot ?? ""), g = S(o.overlays, h, m), _, x;
+	if (g.length === 0) if (x = !1, c !== null) {
+		let e = `data:image/png;base64,${Buffer.from(p).toString("base64")}`;
+		_ = l({ loadSystemFonts: !0 }).toEditablePng({
+			originalDataUrl: e,
+			annotationsSvg: y(),
+			width: m.width,
+			height: m.height,
+			tags: c.tags
+		});
+	} else _ = p;
+	else {
+		let e = `data:image/png;base64,${Buffer.from(p).toString("base64")}`, t = C(g), n = l({ loadSystemFonts: !0 }), r = {
+			originalDataUrl: e,
+			annotationsSvg: t,
+			width: m.width,
+			height: m.height
+		};
+		_ = c === null ? n.toPng(r) : n.toEditablePng({
+			...r,
+			tags: c.tags
+		}), x = !0;
+	}
+	return e.cache && await e.cache.set(d, _), {
+		bytes: _,
+		fromCache: !1,
+		hadBoundingBoxes: x
+	};
+}
+function v(e) {
+	return e ? e === !0 ? {} : e : null;
+}
+function y() {
+	return "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>";
+}
+function b(e) {
+	let t = [];
+	for (let n of e.split(/\r?\n/)) {
+		if (!n.trim()) continue;
+		let e = n.match(/^\s*-\s+([a-z]+)(?:\s+"([^"]*?)")?/);
+		if (!e) continue;
+		let r = e[1] ?? "", i = e[2] ?? "", a = n.match(/\[ref=(e\d+)\]/)?.[1], o = n.match(/\[box=(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\]/);
+		!a || !o || t.push({
+			role: r,
+			name: i,
+			ref: a,
+			box: {
+				x: Number.parseFloat(o[1]),
+				y: Number.parseFloat(o[2]),
+				width: Number.parseFloat(o[3]),
+				height: Number.parseFloat(o[4])
+			}
+		});
+	}
+	return t;
+}
+async function x(e) {
+	let t = e.cwd ?? process.cwd(), n = await u(a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath));
+	if (!n) throw Error(`resolveMdxAnnotations: ${e.mdxPath} has no \`annot:\` frontmatter — cannot resolve.`);
+	let r = n.screens.find((t) => t.id === e.screenId);
+	if (!r) throw Error(`resolveMdxAnnotations: ${e.mdxPath} has no <Screen id="${e.screenId}"> block.`);
+	let i = b(n.commentBlocks.snapshot ?? "");
+	return S(r.overlays, i, e.dims);
+}
+function S(e, t, n) {
+	let r = [], i = 1;
+	for (let a of e) {
+		let e = t.find((e) => e.role === a.match.role && e.name === a.match.name);
+		if (!e) continue;
+		let o = a.number ?? i++;
+		r.push({
+			type: "numberedBadge",
+			bbox: e.box,
+			number: o,
+			placement: "auto",
+			imageWidth: n.width,
+			imageHeight: n.height,
+			intent: a.intent === "action" ? "warning" : a.intent === "required" ? "error" : "info"
+		});
+	}
+	return r;
+}
+function C(e) {
+	return `<svg xmlns="http://www.w3.org/2000/svg">${c(e)}</svg>`;
+}
+function w(e) {
+	return e.length === 0 ? "<svg xmlns=\"http://www.w3.org/2000/svg\"></svg>" : `<svg xmlns="http://www.w3.org/2000/svg">${c(e)}</svg>`;
+}
+async function T(e, t, r) {
+	if (!t) throw Error("renderAnnotatedScreen: <Screen src=...> is required — cannot render without a base image.");
+	let i = await n(a(t) ? t : s(r, t));
+	return new Uint8Array(i.buffer, i.byteOffset, i.byteLength);
+}
+function E(e) {
+	if (e.length < 24) throw Error("renderAnnotatedScreen: base PNG too short to contain IHDR.");
+	let t = new DataView(e.buffer, e.byteOffset, e.byteLength);
+	return {
+		width: t.getUint32(16, !1),
+		height: t.getUint32(20, !1)
+	};
+}
+//#endregion
+export { d as RENDER_PIPELINE_VERSION, f as cacheKey, p as createFileCache, m as createMemoryCache, b as parseSnapshotBoxes, g as productDocsIntegration, _ as renderAnnotatedScreen, x as resolveMdxAnnotations, w as svgFromBboxAnnotations };

package/dist/integration.d.ts

@@ -0,0 +1,46 @@
+import { AstroIntegration } from 'astro';
+export interface ProductDocsIntegrationOptions {
+    /**
+     * Directory (relative to the Astro project root) that contains
+     * the `annot:`-frontmatter MDX files the integration should
+     * walk for the Image Service + component-config defaults.
+     * Default: `"docs"`.
+     */
+    contentDir?: string;
+    /**
+     * Path to the `annot-docs.config.ts` config file. Default:
+     * `"annot-docs.config.ts"`. Future PRs read this for the
+     * `meta` defaults + per-book template lookups.
+     */
+    configPath?: string;
+    /**
+     * If `true`, the integration logs a debug line on every
+     * config:setup. Useful for verifying the integration is
+     * installed correctly in an Astro project. Default: `false`.
+     */
+    verbose?: boolean;
+}
+/**
+ * Astro integration factory. Drop into `astro.config.mjs`:
+ *
+ * ```js
+ * import { defineConfig } from "astro/config";
+ * import { productDocsIntegration } from "@ingcreators/annot-product-docs-astro";
+ *
+ * export default defineConfig({
+ *   integrations: [productDocsIntegration()],
+ * });
+ * ```
+ *
+ * Phase 2 PR 1 ships the scaffold — the hooks are no-ops aside
+ * from optional verbose logging. PR 2 adds the Image Service;
+ * PR 3 wires up the seven docs components.
+ */
+export declare function productDocsIntegration(options?: ProductDocsIntegrationOptions): AstroIntegration;
+/**
+ * Default-export shape some Astro integration authors prefer.
+ * Both `import productDocsIntegration from ...` (default) and
+ * `import { productDocsIntegration }` (named) resolve to the
+ * same factory; consumers can pick whichever feels natural.
+ */
+export default productDocsIntegration;

package/dist/playwright/fixture.d.ts

@@ -0,0 +1,72 @@
+import { BboxAnnotation } from '@ingcreators/annot-annotator';
+/**
+ * Compositional options for `page.screenshot({ annot })` /
+ * `locator.screenshot({ annot })`. Each field is an independent
+ * contribution to the embedded XMP record:
+ *
+ * - `mdx`     — refresh + resolve MDX `<Overlay>` annotations
+ * - `overlays`— inline `BboxAnnotation[]` (the DSL accepted by
+ *               `@ingcreators/annot-annotator`)
+ * - `tags`    — provenance metadata written verbatim into the XMP
+ * - `editable`— bake-vs-preserve toggle (default `true`)
+ *
+ * `annot: true` / `annot: {}` is treated as a no-op shorthand — the
+ * fixture detects no contribution and the screenshot falls through
+ * to vanilla Playwright behaviour.
+ */
+export interface AnnotScreenshotOptions {
+    /** Refresh the MDX `annot:snapshot` block and resolve the
+     *  `<Screen id>`'s overlays. The MDX file is rewritten in-place
+     *  with the current page's aria-snapshot before overlays resolve.
+     */
+    mdx?: {
+        id: string;
+        path: string;
+    };
+    /** Caller-supplied annotations — merged with MDX-derived ones if
+     *  `mdx` is also set. Same DSL `@ingcreators/annot-annotator`
+     *  accepts. */
+    overlays?: BboxAnnotation[];
+    /** Provenance metadata written verbatim into the PNG's XMP. The
+     *  fixture adds no defaults; callers who want `WELL_KNOWN_TAG_KEYS`
+     *  (`source` / `screen` / `capturedAt` / `commit`) write them. */
+    tags?: Record<string, string>;
+    /** When `true` (default): annotations stored as SVG in XMP +
+     *  original capture embedded → re-editable in Annot Cloud. When
+     *  `false`: annotations baked into the visible pixels, no XMP
+     *  layer, no embedded original — flat PNG, no round-trip. */
+    editable?: boolean;
+}
+declare module "@playwright/test" {
+    interface PageScreenshotOptions {
+        annot?: AnnotScreenshotOptions;
+    }
+    interface LocatorScreenshotOptions {
+        annot?: AnnotScreenshotOptions;
+    }
+}
+/**
+ * Idempotent prototype patch — wrap `screenshot` to intercept the
+ * `annot` opt while falling through to the original method when
+ * absent / empty. Exported for unit tests; production usage flows
+ * through the fixture `extend({ page })` body which calls this once
+ * per worker on the first page (and once for the locator prototype).
+ */
+export declare function patchScreenshot(proto: {
+    screenshot: (opts?: unknown) => Promise<Buffer>;
+}): void;
+/**
+ * `test = base.extend({ page })` — drop-in for `@playwright/test`'s
+ * `test` plus a one-time patch of `Page.prototype.screenshot` AND
+ * `Locator.prototype.screenshot` (per worker process) so calls
+ * carrying `annot: { ... }` run the annot pipeline above.
+ *
+ * The base `test` is `@ingcreators/annot-product-docs`'s test which
+ * already extends `@ingcreators/annot-playwright` — callers get
+ * `page` + `annotator` + `screen` plus the annot-aware screenshot.
+ */
+export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
+    annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
+} & {
+    screen: import('@ingcreators/annot-product-docs').Screen;
+}, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;

package/dist/playwright/index.d.ts

@@ -0,0 +1,5 @@
+export { expect } from '@playwright/test';
+export type { AnnotScreenshotOptions } from './fixture.js';
+export { patchScreenshot, test } from './fixture.js';
+export type { Clip, RebaseResult } from './rebase.js';
+export { describeAnnotation, rebaseAnnotations } from './rebase.js';

package/dist/playwright/rebase.d.ts

@@ -0,0 +1,36 @@
+import { BboxAnnotation } from '@ingcreators/annot-annotator';
+export interface Clip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RebaseResult {
+    /** Annotations whose coordinates were rebased into clip-space. */
+    kept: BboxAnnotation[];
+    /** Annotations that fell outside `clip` and were dropped. The
+     *  caller surfaces these as `RenderResult.droppedOverlays` /
+     *  `test.info().annotations` warnings. */
+    dropped: BboxAnnotation[];
+}
+/**
+ * Rebase + filter a `BboxAnnotation[]` against a clip rectangle.
+ *
+ * - `kept` = annotations whose visible coords were translated by
+ *   `(-clip.x, -clip.y)`. The new coords are in the clipped image's
+ *   coordinate space (0,0 at the top-left of the screenshot).
+ * - `dropped` = annotations whose bbox / endpoints fell outside the
+ *   clip. Returned verbatim (un-rebased) so the caller can log
+ *   which originals were skipped.
+ *
+ * `numberedBadge`'s `imageWidth` / `imageHeight` are also rebased
+ * to match the clip dimensions, so `placement: "auto"` picks the
+ * corner against the cropped image edge rather than the page edge.
+ */
+export declare function rebaseAnnotations(annotations: BboxAnnotation[], clip: Clip): RebaseResult;
+/**
+ * Format a short identifier for an annotation so dropped diagnostics
+ * stay readable. We don't have a stable id field on the DSL types —
+ * use `type` + first bbox coords as a heuristic.
+ */
+export declare function describeAnnotation(ann: BboxAnnotation): string;

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.0",
   "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-product-docs": "0.2.0",
+    "@ingcreators/annot-annotator": "0.5.0",
+    "@ingcreators/annot-core": "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",