@ingcreators/annot-product-docs-astro 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ingcreators/annot-product-docs-astro
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [6124d59]
+- Updated dependencies [b5d52f6]
+- Updated dependencies [fa712fd]
+- Updated dependencies [0c7ac26]
+- Updated dependencies [f09a6b1]
+- Updated dependencies [0d19345]
+- Updated dependencies [64dc6e8]
+- Updated dependencies [691bec5]
+- Updated dependencies [9697f27]
+- Updated dependencies [266b05a]
+  - @ingcreators/annot-annotator@0.6.0
+  - @ingcreators/annot-product-docs@0.4.0
+  - @ingcreators/annot-core@0.3.0
+  - @ingcreators/annot-playwright@0.4.1
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/cache.d.ts

@@ -4,8 +4,24 @@
  * 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.
+ *
+ * Bumped to 2 in Phase 1h of
+ * `docs/plans/living-spec-authoring-roadmap.md` — the renderer now
+ * prefers PNG XMP `annot:elementTree` bboxes over the legacy
+ * `annot:snapshot` MDX comment block when both are present. Forcing
+ * a cold cache avoids the stale-cache window where a migrated MDX
+ * (legacy comment block stripped) + new PNG XMP would otherwise
+ * map to the same cache key as the pre-migration state.
+ *
+ * Known limitation: post-migration, re-running the Playwright tour
+ * mutates the PNG XMP without touching the MDX. Today's cache key
+ * doesn't include PNG content, so the cache won't auto-invalidate
+ * on tour re-runs. Workaround until that's fixed: delete the
+ * `.astro/annot-product-docs/` cache directory between tour runs
+ * (or bump this version every time the tour is expected to change
+ * output). A follow-up will fold a PNG content hash into the key.
  */
-export declare const RENDER_PIPELINE_VERSION = 1;
+export declare const RENDER_PIPELINE_VERSION = 2;
 export interface CacheKeyInput {
     mdxSource: string;
     screenId: string;
@@ -16,6 +32,13 @@ export interface CacheKeyInput {
      * historical key shape for flat callers.
      */
     editable?: boolean;
+    /**
+     * Phase 2b: raw bytes of the `<Screen annotations="…">` yaml,
+     * when set. Folded into the cache key so editing the yaml busts
+     * the cached PNG. Undefined when the screen uses the inline
+     * `<Overlay>` path (legacy callers' key shape is preserved).
+     */
+    annotationsYamlSource?: string;
 }
 /**
  * Compute the cache key for a `<Screen>` block. Stable across

package/dist/components/AnnotCallout.astro

@@ -0,0 +1,32 @@
+---
+// `<AnnotCallout>` — Phase 2b of
+// `docs/plans/living-spec-authoring-roadmap.md`. Caption for one
+// callout entry on a `<Screen annotations="…">`. Replaces the
+// inline `<Overlay match intent number>` form: match / intent /
+// number now live in the screen's annotation yaml, and this
+// component carries only the visible body.
+//
+// MDX usage:
+//   <Screen id="login" src="./shots/login.png"
+//           annotations="./annotations/login.yaml">
+//     <AnnotCallout for="o1">**Email** — registered address.</AnnotCallout>
+//     <AnnotCallout for="o2">**Password** — characters hidden.</AnnotCallout>
+//   </Screen>
+//
+// The visible badge / number / intent border is composed onto the
+// annotated PNG by the Image Service (see `../render.ts`). The
+// HTML side emits the body inside a `<li>` so the legend
+// auto-numbers via the surrounding `<ol class="annot-screen-overlays">`
+// counter — no per-call `number` prop required.
+
+interface Props {
+  /** Targets `overlays[].id` in the screen's annotation yaml. */
+  for: string;
+}
+const { for: forId } = Astro.props;
+---
+<li class="annot-callout" data-callout-for={forId}>
+  <div class="annot-callout-body">
+    <slot />
+  </div>
+</li>

package/dist/components/AnnotEditButton.astro

@@ -0,0 +1,186 @@
+---
+// `<AnnotEditButton>` — Phase 5d of
+// `docs/plans/living-spec-authoring-roadmap.md`. Mountable
+// "✏️ Edit" button that routes visitors to the annot-cloud
+// editor at `${cloudUrl}/embed?...`. Phase 5 ships three embed
+// modes:
+//
+//   - `newTab` (default): click → `window.open(...)`. Works
+//     under every Enterprise constraint (CSP / SSO / on-prem /
+//     air-gapped). See OQ-09 in
+//     `living-spec-authoring-roadmap.md`.
+//   - `disabled`: button is not rendered. For read-only docs /
+//     air-gapped deployments without on-prem annot-cloud.
+//   - `inline` (opt-in): modal `<iframe>` mounted on the docs
+//     site. Requires `<AnnotEditorIframeModal />` (5e) to be
+//     mounted somewhere on the same page (typically in the
+//     layout). If the modal isn't present, `inline` gracefully
+//     degrades to `newTab` with a one-time `console.warn`.
+//
+// MDX usage:
+//
+//   <AnnotEditButton
+//     repo="ingcreators/annot"
+//     pngPath="docs/shots/login.png"
+//     annotationsPath="docs/annotations/login.annotations.yaml"
+//   />
+//
+// `cloudUrl` defaults to `https://annot.work`. Override via
+// per-call prop OR (in Phase 5f) `annot-docs.config.ts`'s
+// `editor.cloudUrl` default. The defaults landed here are
+// what Phase 5f will lift into the config; Phase 5d ships
+// per-call props only.
+
+import type { EmbedMode } from "@ingcreators/annot-embed-protocol";
+import { ANNOT_EDITOR_CONFIG } from "../editor-config-virtual.js";
+
+interface Props {
+  /** Owner/repo slug, e.g. `"ingcreators/annot"`. */
+  repo: string;
+  /** Path within the repo of the PNG being edited. */
+  pngPath: string;
+  /** Path within the repo of the linked `.annotations.yaml`. */
+  annotationsPath: string;
+  /** Embed mode. Defaults to the integration-supplied
+   *  `editor.embedMode` (or `"newTab"` if unset). */
+  mode?: EmbedMode;
+  /** Cloud editor origin override. Defaults to the
+   *  integration-supplied `editor.cloudUrl` (or
+   *  `"https://annot.work"` if unset). */
+  cloudUrl?: string;
+  /** Visible button label. Defaults to `"✏️ Edit"`. */
+  label?: string;
+}
+
+const {
+  repo,
+  pngPath,
+  annotationsPath,
+  mode = ANNOT_EDITOR_CONFIG.embedMode,
+  cloudUrl = ANNOT_EDITOR_CONFIG.cloudUrl,
+  label = "✏️ Edit",
+} = Astro.props;
+---
+{
+  mode !== "disabled" && (
+    <button
+      type="button"
+      class="annot-edit-button"
+      data-annot-edit-mode={mode}
+      data-annot-edit-cloud-url={cloudUrl}
+      data-annot-edit-repo={repo}
+      data-annot-edit-png-path={pngPath}
+      data-annot-edit-annotations-path={annotationsPath}
+      aria-label={`Edit ${pngPath}`}
+    >
+      {label}
+    </button>
+  )
+}
+
+<script>
+  import { encodeEmbedRequestUrl } from "@ingcreators/annot-embed-protocol";
+
+  // One-time warning when a `mode="inline"` button is clicked
+  // but `<AnnotEditorIframeModal />` isn't on the page. The
+  // warning lives at the page-script level so multiple buttons
+  // share it.
+  let warnedMissingModal = false;
+
+  interface ModalApi {
+    open: (options: { cloudUrl: string; editorUrl: string }) => void;
+  }
+
+  function findModalApi(): ModalApi | undefined {
+    return (window as unknown as { __annotEditorIframeModal?: ModalApi })
+      .__annotEditorIframeModal;
+  }
+
+  function activate(button: HTMLButtonElement): void {
+    const mode = button.dataset.annotEditMode ?? "newTab";
+    const cloudUrl = button.dataset.annotEditCloudUrl ?? "";
+    const repo = button.dataset.annotEditRepo ?? "";
+    const pngPath = button.dataset.annotEditPngPath ?? "";
+    const annotationsPath = button.dataset.annotEditAnnotationsPath ?? "";
+
+    button.addEventListener("click", () => {
+      // Resolve the effective mode. `inline` falls back to
+      // `newTab` if `<AnnotEditorIframeModal />` isn't on the
+      // page so the button still does something useful (warn
+      // once so authors notice in DevTools).
+      let effectiveMode: "newTab" | "inline" = mode === "inline" ? "inline" : "newTab";
+      const modalApi = effectiveMode === "inline" ? findModalApi() : undefined;
+      if (effectiveMode === "inline" && !modalApi) {
+        if (!warnedMissingModal) {
+          // biome-ignore lint/suspicious/noConsole: degraded-UX surface for the missing modal.
+          console.warn(
+            '[<AnnotEditButton>] mode="inline" requires <AnnotEditorIframeModal /> on the page; falling back to mode="newTab". Mount the modal component in your layout to enable the inline flow.',
+          );
+          warnedMissingModal = true;
+        }
+        effectiveMode = "newTab";
+      }
+
+      const returnUrl = window.location.href.split("#")[0];
+      try {
+        const url = encodeEmbedRequestUrl({
+          cloudUrl,
+          repo,
+          pngPath,
+          annotationsPath,
+          returnUrl,
+          mode: effectiveMode,
+        });
+        if (effectiveMode === "inline" && modalApi) {
+          modalApi.open({ cloudUrl, editorUrl: url });
+          return;
+        }
+        window.open(url, "_blank", "noopener,noreferrer");
+      } catch (error) {
+        // biome-ignore lint/suspicious/noConsole: encoder errors surface as runtime warnings.
+        console.error("[<AnnotEditButton>] failed to build embed URL:", error);
+      }
+    });
+  }
+
+  function init(): void {
+    const buttons = document.querySelectorAll<HTMLButtonElement>(
+      "button.annot-edit-button",
+    );
+    for (const button of Array.from(buttons)) {
+      activate(button);
+    }
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+</script>
+
+<style>
+  .annot-edit-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4em;
+    padding: 0.4em 0.8em;
+    font-family: inherit;
+    font-size: 0.9em;
+    line-height: 1.2;
+    color: var(--annot-edit-button-fg, #ffffff);
+    background: var(--annot-edit-button-bg, #3b82f6);
+    border: 0;
+    border-radius: 0.4em;
+    cursor: pointer;
+    transition: background 0.15s ease-out;
+  }
+  .annot-edit-button:hover,
+  .annot-edit-button:focus-visible {
+    background: var(--annot-edit-button-bg-hover, #2563eb);
+    outline: none;
+  }
+  .annot-edit-button:focus-visible {
+    box-shadow: 0 0 0 2px var(--annot-edit-button-focus-ring, #93c5fd);
+  }
+</style>

package/dist/components/AnnotEditCompleteListener.astro

@@ -0,0 +1,186 @@
+---
+// `<AnnotEditCompleteListener>` — Phase 5g of
+// `docs/plans/living-spec-authoring-roadmap.md`.
+//
+// Invisible client-side component that surfaces a transient
+// toast when the cloud editor returns control to the docs site
+// after a save. Two trigger paths:
+//
+//   - `newTab` mode: the cloud editor redirects to
+//     `${returnUrl}#edit-complete=<editId>`. On client-side mount
+//     this component parses `window.location.hash` via the 5b
+//     `parseEmbedReturnHash` codec, renders a toast when the
+//     hash carries an `EmbedReturnSignal` of kind `"complete"`,
+//     and dispatches an `annot:edit-complete` `CustomEvent` on
+//     `document` so downstream listeners (analytics, custom
+//     rebuild-status badges) can react.
+//
+//   - `inline` mode: the 5e `<AnnotEditorIframeModal>` already
+//     dismisses itself on `EditCommitted`. This component
+//     listens for the same lifecycle event via an
+//     `annot-editor-iframe-modal-event` `CustomEvent` the 5e
+//     modal dispatches on `document`, then renders the same
+//     toast.
+//
+// Mount once per page (typically inside the layout). Multiple
+// instances are safe — only the first activates; the rest
+// short-circuit on init via the `data-annot-edit-complete-listener-active`
+// marker.
+
+interface Props {
+  /** Toast message override. Defaults to "Edit saved — site
+   *  rebuilds in ~1 minute." */
+  message?: string;
+  /** Auto-dismiss timeout in milliseconds. Defaults to 8000.
+   *  Set to `0` to keep the toast visible until the user
+   *  dismisses it manually. */
+  dismissAfterMs?: number;
+}
+
+const { message = "Edit saved — site rebuilds in ~1 minute.", dismissAfterMs = 8000 } =
+  Astro.props;
+---
+
+<div
+  class="annot-edit-complete-listener"
+  data-annot-edit-complete-listener-root
+  data-annot-edit-complete-message={message}
+  data-annot-edit-complete-dismiss-ms={dismissAfterMs}
+  aria-live="polite"
+  aria-atomic="true"
+>
+  <slot />
+</div>
+
+<script>
+  import { parseEmbedReturnHash } from "@ingcreators/annot-embed-protocol";
+
+  const ROOT_SELECTOR = "[data-annot-edit-complete-listener-root]";
+  const ACTIVE_MARKER = "data-annot-edit-complete-listener-active";
+  const TOAST_DISMISS_FALLBACK_MS = 8000;
+
+  interface Detail {
+    readonly editId: string;
+    readonly source: "newTab" | "inline";
+  }
+
+  function findRoot(): HTMLElement | null {
+    // Pick the FIRST listener mounted on the page. Multiple
+    // copies are safe; subsequent ones short-circuit.
+    return document.querySelector<HTMLElement>(ROOT_SELECTOR);
+  }
+
+  function showToast(root: HTMLElement, detail: Detail): void {
+    const message = root.dataset.annotEditCompleteMessage ?? "Edit saved.";
+    const dismissAfterMs = Number(
+      root.dataset.annotEditCompleteDismissMs ?? TOAST_DISMISS_FALLBACK_MS,
+    );
+
+    const toast = document.createElement("div");
+    toast.className = "annot-edit-complete-toast";
+    toast.setAttribute("role", "status");
+    toast.dataset.annotEditCompleteId = detail.editId;
+    toast.dataset.annotEditCompleteSource = detail.source;
+    toast.textContent = message;
+
+    const dismissBtn = document.createElement("button");
+    dismissBtn.type = "button";
+    dismissBtn.className = "annot-edit-complete-toast-dismiss";
+    dismissBtn.setAttribute("aria-label", "Dismiss notification");
+    dismissBtn.textContent = "×";
+    dismissBtn.addEventListener("click", () => {
+      toast.remove();
+    });
+    toast.appendChild(dismissBtn);
+
+    root.appendChild(toast);
+
+    if (Number.isFinite(dismissAfterMs) && dismissAfterMs > 0) {
+      window.setTimeout(() => {
+        toast.remove();
+      }, dismissAfterMs);
+    }
+
+    document.dispatchEvent(
+      new CustomEvent("annot:edit-complete", { detail }),
+    );
+  }
+
+  function consumeReturnHash(root: HTMLElement): void {
+    const signal = parseEmbedReturnHash(window.location.hash);
+    if (!signal || signal.kind !== "complete") return;
+    showToast(root, { editId: signal.editId, source: "newTab" });
+    // Clear the hash so a page refresh doesn't re-toast.
+    if (typeof window.history.replaceState === "function") {
+      const cleanUrl = `${window.location.pathname}${window.location.search}`;
+      window.history.replaceState(null, "", cleanUrl);
+    }
+  }
+
+  function attachInlineListener(root: HTMLElement): void {
+    document.addEventListener("annot:editor-iframe-committed", (event: Event) => {
+      const detail = (event as CustomEvent<{ editId?: string }>).detail;
+      const editId = detail?.editId ?? "";
+      if (!editId) return;
+      showToast(root, { editId, source: "inline" });
+    });
+  }
+
+  function init(): void {
+    const root = findRoot();
+    if (!root) return;
+    if (root.hasAttribute(ACTIVE_MARKER)) return;
+    root.setAttribute(ACTIVE_MARKER, "1");
+
+    consumeReturnHash(root);
+    attachInlineListener(root);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+</script>
+
+<style>
+  .annot-edit-complete-listener {
+    position: fixed;
+    bottom: 1.5rem;
+    right: 1.5rem;
+    z-index: 9999;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    pointer-events: none;
+  }
+  .annot-edit-complete-toast {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.75rem 1rem;
+    color: var(--annot-edit-toast-fg, #ffffff);
+    background: var(--annot-edit-toast-bg, #16a34a);
+    border-radius: 0.4em;
+    box-shadow: 0 0.25rem 0.75rem rgba(0, 0, 0, 0.25);
+    font-family: inherit;
+    font-size: 0.95em;
+    line-height: 1.3;
+    pointer-events: auto;
+  }
+  .annot-edit-complete-toast-dismiss {
+    margin-left: auto;
+    background: transparent;
+    border: 0;
+    color: inherit;
+    font-size: 1.25em;
+    line-height: 1;
+    cursor: pointer;
+    padding: 0 0.25em;
+  }
+  .annot-edit-complete-toast-dismiss:hover,
+  .annot-edit-complete-toast-dismiss:focus-visible {
+    opacity: 0.8;
+    outline: none;
+  }
+</style>

package/dist/components/AnnotEditorIframeModal.astro

@@ -0,0 +1,202 @@
+---
+// `<AnnotEditorIframeModal>` — Phase 5e of
+// `docs/plans/living-spec-authoring-roadmap.md`. The inline-
+// mode counterpart to `<AnnotEditButton>`'s default newTab
+// behaviour. Mount once per page (typically in the docs site's
+// layout) and any `<AnnotEditButton mode="inline">` on the
+// same page opens the modal instead of a new tab.
+//
+// Lazy-loaded: the modal HTML + script only ship if this
+// component is mounted. Pages that only use `mode="newTab"`
+// (the default per OQ-09) never download the modal code.
+// `<AnnotEditButton mode="inline">` on a page without
+// `<AnnotEditorIframeModal />` gracefully degrades to newTab
+// + a one-time `console.warn`.
+//
+// MDX usage in a layout:
+//
+//   ---
+//   import { AnnotEditorIframeModal } from "@ingcreators/annot-product-docs-astro/components/AnnotEditorIframeModal.astro";
+//   ---
+//   <slot />
+//   <AnnotEditorIframeModal />
+//
+// Then any `<AnnotEditButton mode="inline" ... />` in MDX
+// opens the modal on click. The modal listens for
+// `EditCommitted` / `EditAbandoned` / `ResizeNeeded` via the
+// 5c postMessage dispatcher and dismisses itself accordingly.
+
+interface Props {
+  /** Modal aria-label. Overridable for localisation. */
+  ariaLabel?: string;
+}
+
+const { ariaLabel = "Annot editor" } = Astro.props;
+---
+
+<dialog
+  class="annot-editor-iframe-modal"
+  data-annot-edit-modal-root
+  aria-label={ariaLabel}
+>
+  <iframe
+    class="annot-editor-iframe-modal-frame"
+    title={ariaLabel}
+    allow="clipboard-read; clipboard-write"
+    referrerpolicy="origin"
+  ></iframe>
+</dialog>
+
+<script>
+  import {
+    createEmbedHostMessenger,
+    type EmbedEvent,
+    type EmbedMessenger,
+  } from "@ingcreators/annot-embed-protocol";
+
+  interface OpenModalOptions {
+    readonly cloudUrl: string;
+    readonly editorUrl: string;
+  }
+
+  const MAX_HEIGHT_FRACTION = 0.95;
+  const DEFAULT_FRAME_HEIGHT_PX = 720;
+
+  function findModal(): HTMLDialogElement | null {
+    return document.querySelector<HTMLDialogElement>(
+      "dialog[data-annot-edit-modal-root]",
+    );
+  }
+
+  function findFrame(modal: HTMLDialogElement): HTMLIFrameElement | null {
+    return modal.querySelector<HTMLIFrameElement>(
+      "iframe.annot-editor-iframe-modal-frame",
+    );
+  }
+
+  function clampHeight(requested: number): number {
+    if (!Number.isFinite(requested) || requested <= 0) {
+      return DEFAULT_FRAME_HEIGHT_PX;
+    }
+    const max = window.innerHeight * MAX_HEIGHT_FRACTION;
+    return Math.min(requested, max);
+  }
+
+  function openModal(options: OpenModalOptions): void {
+    const modal = findModal();
+    if (!modal) {
+      // biome-ignore lint/suspicious/noConsole: lazy-mount contract violation surfaces here.
+      console.warn(
+        "[<AnnotEditorIframeModal>] dialog element not found — was the component mounted on this page?",
+      );
+      return;
+    }
+    const frame = findFrame(modal);
+    if (!frame) return;
+
+    frame.style.height = `${DEFAULT_FRAME_HEIGHT_PX}px`;
+    frame.src = options.editorUrl;
+
+    let messenger: EmbedMessenger | null = null;
+
+    const teardown = (): void => {
+      if (messenger) {
+        messenger.cleanup();
+        messenger = null;
+      }
+      frame.removeAttribute("src");
+    };
+
+    const onEvent = (event: EmbedEvent): void => {
+      if (event.type === "EditCommitted") {
+        // Forward to the docs-site's `<AnnotEditCompleteListener>` so the
+        // post-edit toast surfaces consistently across newTab + inline
+        // modes (Phase 5g).
+        document.dispatchEvent(
+          new CustomEvent("annot:editor-iframe-committed", {
+            detail: {
+              editId: event.editId,
+              commitSha: event.commitSha,
+              branch: event.branch,
+              prUrl: event.prUrl,
+            },
+          }),
+        );
+        modal.close();
+        return;
+      }
+      if (event.type === "EditAbandoned") {
+        modal.close();
+        return;
+      }
+      if (event.type === "ResizeNeeded") {
+        frame.style.height = `${clampHeight(event.height)}px`;
+      }
+    };
+
+    modal.addEventListener(
+      "close",
+      () => {
+        teardown();
+      },
+      { once: true },
+    );
+
+    // Set up the host messenger after the iframe loads — its
+    // `contentWindow` is null until then. Once loaded, attach
+    // the messenger; subsequent postMessages from the cloud
+    // editor route through it.
+    frame.addEventListener(
+      "load",
+      () => {
+        try {
+          messenger = createEmbedHostMessenger({
+            frame,
+            expectedOrigin: options.cloudUrl,
+            onEvent,
+          });
+        } catch (error) {
+          // biome-ignore lint/suspicious/noConsole: surface failed host-messenger setup.
+          console.error("[<AnnotEditorIframeModal>] failed to attach host messenger:", error);
+          modal.close();
+        }
+      },
+      { once: true },
+    );
+
+    modal.showModal();
+  }
+
+  // Expose the open function for `<AnnotEditButton>`'s inline-
+  // mode click handler to call. Keep the surface narrow — just
+  // `open` — so future expansion (close-from-outside,
+  // post-event listener API) is additive.
+  type ModalApi = {
+    open: (options: OpenModalOptions) => void;
+  };
+  (window as unknown as { __annotEditorIframeModal?: ModalApi }).__annotEditorIframeModal =
+    { open: openModal };
+</script>
+
+<style>
+  .annot-editor-iframe-modal {
+    width: min(95vw, 1280px);
+    max-width: 95vw;
+    max-height: 95vh;
+    padding: 0;
+    border: 0;
+    border-radius: 0.6em;
+    background: var(--annot-editor-modal-bg, #ffffff);
+    box-shadow: 0 0.5em 2em rgba(0, 0, 0, 0.4);
+    overflow: hidden;
+  }
+  .annot-editor-iframe-modal::backdrop {
+    background: rgba(0, 0, 0, 0.5);
+  }
+  .annot-editor-iframe-modal-frame {
+    display: block;
+    width: 100%;
+    min-height: 360px;
+    border: 0;
+  }
+</style>

package/dist/components/Screen.astro

@@ -1,27 +1,47 @@
 ---
 // `<Screen>` — annotated screenshot block.
 //
-// MDX usage:
+// MDX usage (legacy, inline `<Overlay>` callouts):
 //   <Screen id="login" src="./shots/login.png">
 //     <Overlay match={...} number={1}>...</Overlay>
 //   </Screen>
 //
+// MDX usage (Phase 2b, yaml-driven callouts):
+//   <Screen id="login" src="./shots/login.png"
+//           annotations="./annotations/login.yaml">
+//     <AnnotCallout for="o1">...</AnnotCallout>
+//   </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.
+// `../render.ts`). When `annotations` is set, the service reads
+// the yaml + composes badges from `overlays[]`; otherwise it
+// resolves the inline `<Overlay match>` children. 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;
+  /**
+   * Phase 2b of `docs/plans/living-spec-authoring-roadmap.md`.
+   * Path (relative to the MDX file) to an `.annotations.yaml`
+   * file describing the screen's overlays. When set, the Image
+   * Service prefers yaml-driven badge composition over the
+   * legacy inline `<Overlay>` children.
+   */
+  annotations?: string;
 }
-const { id, src, alt } = Astro.props;
+const { id, src, alt, annotations } = Astro.props;
 ---
-<figure class="annot-screen" data-screen-id={id}>
+<figure
+  class="annot-screen"
+  data-screen-id={id}
+  data-annotations-path={annotations}
+>
   <img src={src} alt={alt ?? `Screen ${id}`} loading="lazy" />
-  <div class="annot-screen-overlays" data-screen-overlays={id}>
+  <ol class="annot-screen-overlays" data-screen-overlays={id}>
     <slot />
-  </div>
+  </ol>
 </figure>

package/dist/editor-config-virtual.d.ts

@@ -0,0 +1,12 @@
+import { EmbedMode } from '@ingcreators/annot-embed-protocol';
+export interface ResolvedEditorConfig {
+    readonly embedMode: EmbedMode;
+    readonly cloudUrl: string;
+}
+/**
+ * Phase 5 OSS-side built-in defaults. Mirror the per-component
+ * defaults declared inside `<AnnotEditButton>` (`mode="newTab"`,
+ * `cloudUrl="https://annot.work"`) so consumers without the
+ * integration installed still see consistent behaviour.
+ */
+export declare const ANNOT_EDITOR_CONFIG: ResolvedEditorConfig;

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 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 { ResolvedEditorConfig } from './editor-config-virtual.js';
+export { ANNOT_EDITOR_CONFIG } from './editor-config-virtual.js';
+export type { ProductDocsEditorOptions, ProductDocsIntegrationOptions, } from './integration.js';
+export { editorConfigVirtualPlugin, productDocsIntegration, resolveEditorConfig, } from './integration.js';
 export type { RenderAnnotatedScreenOptions, RenderResult, } from './render.js';
 export { renderAnnotatedScreen, resolveMdxAnnotations, svgFromBboxAnnotations } from './render.js';

package/dist/index.js

@@ -1,15 +1,16 @@
 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 { createAnnotator as c } from "@ingcreators/annot-annotator";
-import { buildBadgeAnnotations as l, emptyAnnotationsSvg as u, parseMdxFile as d, parseSnapshotBoxes as f, resolveMdxAnnotations as p, svgFromBadges as m, svgFromBboxAnnotations as h } from "@ingcreators/annot-product-docs";
+import { burnRedactions as c, createAnnotator as l } from "@ingcreators/annot-annotator";
+import { readElementTreePng as u } from "@ingcreators/annot-core";
+import { buildBadgeAnnotations as d, buildBadgeAnnotationsFromYaml as f, buildRasterRedactRegionsFromYaml as p, buildShapeAnnotationsFromYaml as m, elementTreeToBoxedEntries as h, emptyAnnotationsSvg as g, parseAnnotationsYaml as _, parseMdxFile as v, parseSnapshotBoxes as y, resolveMdxAnnotations as b, svgFromBboxAnnotations as x, svgFromBboxAnnotations as S, warnLegacyOverlay as C } from "@ingcreators/annot-product-docs";
 //#region src/cache.ts
-var g = 1;
-function _(t) {
+var w = 2;
+function T(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");
+	return n.update("v2\n"), n.update(t.mdxSource), n.update("\0"), n.update(t.screenId), t.editable && n.update("\0editable"), t.annotationsYamlSource !== void 0 && (n.update("\0annotationsYaml\0"), n.update(t.annotationsYamlSource)), n.digest("hex");
 }
-function v(e) {
+function E(e) {
 	return {
 		dir: e,
 		async get(t) {
@@ -27,7 +28,7 @@ function v(e) {
 		}
 	};
 }
-function y() {
+function D() {
 	let e = /* @__PURE__ */ new Map();
 	return {
 		dir: ":memory:",
@@ -40,79 +41,133 @@ function y() {
 	};
 }
 //#endregion
-//#region src/integration.ts
-var b = "@ingcreators/annot-product-docs-astro";
-function x(e = {}) {
+//#region src/editor-config-virtual.ts
+var O = {
+	embedMode: "newTab",
+	cloudUrl: "https://annot.work"
+}, k = "@ingcreators/annot-product-docs-astro", A = {
+	embedMode: "newTab",
+	cloudUrl: "https://annot.work"
+}, j = "virtual:annot-docs/editor-config", M = `\0${j}`, N = "editor-config-virtual";
+function P(e) {
+	return {
+		name: "annot-docs:editor-config-virtual",
+		enforce: "pre",
+		resolveId(e) {
+			return e === j || e.endsWith(`${N}.ts`) || e.endsWith(`${N}.js`) ? M : null;
+		},
+		load(t) {
+			return t === M ? `export const ANNOT_EDITOR_CONFIG = ${JSON.stringify(e)};\n` : null;
+		}
+	};
+}
+function F(e) {
+	return {
+		embedMode: e?.embedMode ?? A.embedMode,
+		cloudUrl: e?.cloudUrl ?? A.cloudUrl
+	};
+}
+function I(e = {}) {
 	let t = {
 		contentDir: e.contentDir ?? "docs",
 		configPath: e.configPath ?? "annot-docs.config.ts",
+		editor: e.editor,
 		verbose: e.verbose ?? !1
-	};
+	}, n = F(t.editor);
 	return {
-		name: b,
-		hooks: { "astro:config:setup": ({ logger: e }) => {
-			t.verbose && e.info(`${b} installed — contentDir=${t.contentDir} configPath=${t.configPath}`);
+		name: k,
+		hooks: { "astro:config:setup": ({ logger: e, updateConfig: r }) => {
+			t.verbose && e.info(`${k} installed — contentDir=${t.contentDir} configPath=${t.configPath} editor.embedMode=${n.embedMode} editor.cloudUrl=${n.cloudUrl}`), r({ vite: { plugins: [P(n)] } });
 		} }
 	};
 }
 //#endregion
 //#region src/render.ts
-async function S(e) {
-	let t = e.cwd ?? process.cwd(), n = a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath), r = await d(n);
+async function L(e) {
+	let t = e.cwd ?? process.cwd(), n = a(e.mdxPath) ? e.mdxPath : s(t, e.mdxPath), r = await v(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 p = C(e.editable), h = _({
+	let u = R(e.editable), _ = i(n), b = await B(o.annotations, _), x = T({
 		mdxSource: r.source,
 		screenId: e.screenId,
-		editable: p !== null
+		editable: u !== null,
+		annotationsYamlSource: b?.source
 	});
 	if (e.cache) {
-		let t = await e.cache.get(h);
+		let t = await e.cache.get(x);
 		if (t) return {
 			bytes: t,
 			fromCache: !0,
 			hadBoundingBoxes: !0
 		};
 	}
-	let g = e.basePngBytes ?? await w(r, o.src, i(n)), v = T(g), y = f(r.commentBlocks.snapshot ?? ""), b = l(o.overlays, y, v), x, S;
-	if (b.length === 0) if (S = !1, p !== null) {
-		let e = `data:image/png;base64,${Buffer.from(g).toString("base64")}`;
-		x = c({ loadSystemFonts: !0 }).toEditablePng({
+	let w = e.basePngBytes ?? await V(r, o.src, _), E = H(w), D, O = z(w);
+	D = O ? h(O) : y(r.commentBlocks.snapshot ?? "");
+	let k = b && b.file.annotations ? p(b.file.annotations, D) : [], A = k.length > 0 ? await c(w, k) : w;
+	!b && o.overlays.length > 0 && C({
+		mdxPath: e.mdxPath,
+		screenId: e.screenId,
+		overlayCount: o.overlays.length
+	});
+	let j = b ? f(b.file.overlays, D, E) : d(o.overlays, D, E), M = [...b && b.file.annotations ? m(b.file.annotations, D, E) : [], ...j], N, P;
+	if (M.length === 0) if (P = k.length > 0, u !== null) {
+		let e = `data:image/png;base64,${Buffer.from(A).toString("base64")}`;
+		N = l({ loadSystemFonts: !0 }).toEditablePng({
 			originalDataUrl: e,
-			annotationsSvg: u(),
-			width: v.width,
-			height: v.height,
-			tags: p.tags
+			annotationsSvg: g(),
+			width: E.width,
+			height: E.height,
+			tags: u.tags
 		});
-	} else x = g;
+	} else N = A;
 	else {
-		let e = `data:image/png;base64,${Buffer.from(g).toString("base64")}`, t = m(b), n = c({ loadSystemFonts: !0 }), r = {
+		let e = `data:image/png;base64,${Buffer.from(A).toString("base64")}`, t = S(M), n = l({ loadSystemFonts: !0 }), r = {
 			originalDataUrl: e,
 			annotationsSvg: t,
-			width: v.width,
-			height: v.height
+			width: E.width,
+			height: E.height
 		};
-		x = p === null ? n.toPng(r) : n.toEditablePng({
+		N = u === null ? n.toPng(r) : n.toEditablePng({
 			...r,
-			tags: p.tags
-		}), S = !0;
+			tags: u.tags
+		}), P = !0;
 	}
-	return e.cache && await e.cache.set(h, x), {
-		bytes: x,
+	return e.cache && await e.cache.set(x, N), {
+		bytes: N,
 		fromCache: !1,
-		hadBoundingBoxes: S
+		hadBoundingBoxes: P
 	};
 }
-function C(e) {
+function R(e) {
 	return e ? e === !0 ? {} : e : null;
 }
-async function w(e, t, r) {
+function z(e) {
+	try {
+		return u(e);
+	} catch {
+		return null;
+	}
+}
+async function B(e, t) {
+	if (!e) return null;
+	let r = a(e) ? e : s(t, e), i;
+	try {
+		i = await n(r, "utf8");
+	} catch (t) {
+		throw Error(`renderAnnotatedScreen: <Screen annotations="${e}"> — failed to read ${r}: ${t.message}`);
+	}
+	return {
+		file: _(i),
+		source: i
+	};
+}
+async function V(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 T(e) {
+function H(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 {
@@ -121,4 +176,4 @@ function T(e) {
 	};
 }
 //#endregion
-export { g as RENDER_PIPELINE_VERSION, _ as cacheKey, v as createFileCache, y as createMemoryCache, x as productDocsIntegration, S as renderAnnotatedScreen, p as resolveMdxAnnotations, h as svgFromBboxAnnotations };
+export { O as ANNOT_EDITOR_CONFIG, w as RENDER_PIPELINE_VERSION, T as cacheKey, E as createFileCache, D as createMemoryCache, P as editorConfigVirtualPlugin, I as productDocsIntegration, L as renderAnnotatedScreen, F as resolveEditorConfig, b as resolveMdxAnnotations, x as svgFromBboxAnnotations };

package/dist/integration.d.ts

@@ -1,4 +1,27 @@
+import { EmbedMode } from '@ingcreators/annot-embed-protocol';
 import { AstroIntegration } from 'astro';
+import { ResolvedEditorConfig } from './editor-config-virtual.js';
+export interface EditorConfigVitePlugin {
+    readonly name: string;
+    readonly enforce?: "pre" | "post";
+    readonly resolveId: (id: string) => string | null;
+    readonly load: (id: string) => string | null;
+}
+export interface ProductDocsEditorOptions {
+    /**
+     * Default embed mode for every `<AnnotEditButton>` in the
+     * site. Per-call `mode` prop wins when set. Defaults to
+     * `"newTab"`.
+     */
+    embedMode?: EmbedMode;
+    /**
+     * Cloud editor origin override for on-prem deployments
+     * (e.g. `"https://annot.internal.example.com"`). Per-call
+     * `cloudUrl` prop wins when set. Defaults to
+     * `"https://annot.work"`.
+     */
+    cloudUrl?: string;
+}
 export interface ProductDocsIntegrationOptions {
     /**
      * Directory (relative to the Astro project root) that contains
@@ -13,6 +36,11 @@ export interface ProductDocsIntegrationOptions {
      * `meta` defaults + per-book template lookups.
      */
     configPath?: string;
+    /**
+     * Project-wide `<AnnotEditButton>` defaults. Phase 5f of
+     * `docs/plans/living-spec-authoring-roadmap.md`.
+     */
+    editor?: ProductDocsEditorOptions;
     /**
      * If `true`, the integration logs a debug line on every
      * config:setup. Useful for verifying the integration is
@@ -20,6 +48,28 @@ export interface ProductDocsIntegrationOptions {
      */
     verbose?: boolean;
 }
+/**
+ * Vite plugin that:
+ *
+ *   1. Generates a virtual module (`virtual:annot-docs/editor-config`)
+ *      exporting the resolved editor config.
+ *
+ *   2. Aliases every import of the package's
+ *      `editor-config-virtual.ts` to the virtual module so
+ *      `<AnnotEditButton>` picks up the project-wide defaults.
+ *
+ * Exported here for vitest. Consumers don't need to import it
+ * directly — `productDocsIntegration` wires it up automatically.
+ */
+export declare function editorConfigVirtualPlugin(resolved: ResolvedEditorConfig): EditorConfigVitePlugin;
+/**
+ * Merge the per-call editor options into the built-in defaults.
+ * Future revision (Phase 5f follow-up if needed) also reads
+ * `annot-docs.config.ts`'s `editor` config + merges in the
+ * middle of this precedence ladder; today the integration
+ * option is the only override layer.
+ */
+export declare function resolveEditorConfig(editor: ProductDocsEditorOptions | undefined): ResolvedEditorConfig;
 /**
  * Astro integration factory. Drop into `astro.config.mjs`:
  *
@@ -28,19 +78,19 @@ export interface ProductDocsIntegrationOptions {
  * import { productDocsIntegration } from "@ingcreators/annot-product-docs-astro";
  *
  * export default defineConfig({
- *   integrations: [productDocsIntegration()],
+ *   integrations: [
+ *     productDocsIntegration({
+ *       editor: {
+ *         embedMode: "newTab",
+ *         cloudUrl: "https://annot.internal.example.com",
+ *       },
+ *     }),
+ *   ],
  * });
  * ```
- *
- * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs-astro",
-  "version": "0.3.0",
+  "version": "0.3.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",
@@ -39,6 +39,10 @@
     },
     "./components/Screen.astro": "./dist/components/Screen.astro",
     "./components/Overlay.astro": "./dist/components/Overlay.astro",
+    "./components/AnnotCallout.astro": "./dist/components/AnnotCallout.astro",
+    "./components/AnnotEditButton.astro": "./dist/components/AnnotEditButton.astro",
+    "./components/AnnotEditorIframeModal.astro": "./dist/components/AnnotEditorIframeModal.astro",
+    "./components/AnnotEditCompleteListener.astro": "./dist/components/AnnotEditCompleteListener.astro",
     "./components/Transition.astro": "./dist/components/Transition.astro",
     "./components/TransitionTable.astro": "./dist/components/TransitionTable.astro",
     "./components/HistoryEntry.astro": "./dist/components/HistoryEntry.astro",
@@ -54,17 +58,18 @@
     "access": "public"
   },
   "devDependencies": {
-    "@playwright/test": "^1.50.0",
-    "astro": "^6.3.6",
+    "@playwright/test": "^1.61.1",
+    "astro": "^6.4.8",
     "typescript": "^6.0.3",
-    "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.1"
+    "vite": "^8.0.16",
+    "vite-plugin-dts": "^5.0.3"
   },
   "dependencies": {
-    "@ingcreators/annot-annotator": "0.5.0",
-    "@ingcreators/annot-core": "0.2.1",
-    "@ingcreators/annot-product-docs": "0.3.0",
-    "@ingcreators/annot-playwright": "0.4.0"
+    "@ingcreators/annot-core": "0.3.0",
+    "@ingcreators/annot-annotator": "0.6.0",
+    "@ingcreators/annot-embed-protocol": "0.1.0",
+    "@ingcreators/annot-product-docs": "0.4.0",
+    "@ingcreators/annot-playwright": "0.4.1"
   },
   "peerDependencies": {
     "astro": "^5.0.0 || ^6.0.0"