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

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # @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
+
+- f5dc7cb: **`@ingcreators/annot-product-docs-astro/playwright` becomes a
+  deprecated re-export** — Phase 4 of
+  `docs/plans/playwright-screenshot-fixture-relayer.md`. The fixture
+  that originally lived here moved to `@ingcreators/annot-playwright`
+  (generic patch) + `@ingcreators/annot-product-docs` (MDX resolver)
+  in Phases 1–3 of the plan. Phase 4 deletes the duplicate code
+  from this package and converts the `/playwright` subpath into a
+  shim that re-exports the canonical surface so existing callers
+  keep compiling.
+
+  ```ts
+  // Was:
+  import { test } from "@ingcreators/annot-product-docs-astro/playwright";
+
+  // Now (recommended):
+  import { test } from "@ingcreators/annot-product-docs"; // with MDX
+  // or
+  import { test } from "@ingcreators/annot-playwright"; // without MDX
+  ```
+
+  The deprecated subpath emits a one-time
+  `process.emitWarning("DeprecationWarning", …)` at import time so
+  the migration prompt shows up in CI logs. **Reference equality
+  preserved** — `test`, `expect`, `patchScreenshot`,
+  `rebaseAnnotations`, `describeAnnotation` are reference-equal to
+  their canonical homes; a new
+  `packages/product-docs-astro/src/playwright/index.test.ts`
+  asserts this.
+
+  **Removal target**: `@ingcreators/annot-product-docs-astro@0.5.0`,
+  matching the OQ-2 decision (b) in the parent plan — visible
+  deprecation, known sunset.
+
+  ## render.ts switches to the canonical helpers
+
+  `renderAnnotatedScreen()` previously carried its own copies of
+  `resolveMdxAnnotations` / `parseSnapshotBoxes` /
+  `buildBadgeAnnotations` / `svgFromBadges` / `svgFromBboxAnnotations`
+  / `emptyAnnotationsSvg`. Phase 2 of the plan moved the canonical
+  home into `@ingcreators/annot-product-docs`; this PR deletes the
+  duplicates from `product-docs-astro/render.ts` and consumes the
+  ones in product-docs going forward.
+
+  `resolveMdxAnnotations` + `svgFromBboxAnnotations` are re-exported
+  from `render.ts` for one deprecation cycle so existing callers
+  that imported them from `@ingcreators/annot-product-docs-astro`
+  keep compiling. `parseSnapshotBoxes` is dropped from the public
+  surface — new code should import it from
+  `@ingcreators/annot-product-docs` directly.
+
+  ## peerDependencies cleanup
+
+  `@playwright/test` is removed from `peerDependencies` (and from
+  `peerDependenciesMeta`). The package no longer has a Playwright
+  relationship to advertise — the `/playwright` subpath is purely
+  a re-export shim, and its types flow through the
+  `@ingcreators/annot-product-docs` workspace dep transitively.
+  This matches the OQ-3 decision (b) in the parent plan.
+
+  ## Verified
+  - `pnpm -r typecheck` — 20 packages, all pass.
+  - `pnpm test` — 252 files, 3641 tests, 0 failures. New
+    `playwright/index.test.ts` (5 reference-equality assertions)
+    passes; the deprecation `process.emitWarning` fires on
+    import (visible in vitest output) but does not break anything.
+  - `pnpm lint` — exit 0; 29 pre-existing warnings unchanged.
+  - `pnpm --filter @ingcreators/annot-product-docs-astro build` —
+    emits `dist/index.js` (3.96 kB / 1.71 kB gzip) +
+    `dist/playwright/index.js` (0.85 kB / 0.39 kB gzip) — the
+    shrunken subpath bundle reflects the re-export-only shape.
+
+### Patch Changes
+
+- 85d40e6: **Docs + CLAUDE.md + plan archive** — Phase 5 (final) of
+  `docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
+  Refreshes the doc surfaces, the operational CLAUDE.md notes,
+  and archives the relayer plan into `_done/`.
+
+  ## Doc surface updates
+  - `packages/docs-site/src/content/docs/product-docs/playwright-fixture.mdx`
+    — recommended import paths updated; new "Choosing your import"
+    section covers the `@ingcreators/annot-product-docs` (MDX)
+    vs. `@ingcreators/annot-playwright` (no MDX) split; companion
+    helpers section now imports from the canonical homes; codegen
+    workflow example swapped to `@ingcreators/annot-product-docs`.
+  - `packages/docs-site/src/content/docs/api/create-annotator.mdx`
+    — "From a Playwright test" example imports from the canonical
+    home; mentions the no-MDX alternative.
+  - `packages/playwright/README.md` — adds the
+    `page.screenshot({ annot: { … } })` (recommended) section
+    above the existing `annotator.annotateScreenshot(...)` flow;
+    documents the `annotSourceResolvers` extension hook + the
+    coordinate-rebase helpers.
+  - `packages/product-docs/README.md` — adds a `page.screenshot({
+annot })` Playwright fixture section explaining the
+    productDocs.sync + MDX-resolver bundle.
+  - `packages/product-docs-astro/README.md` — replaces the
+    Playwright fixture section with a Migration note pointing at
+    the canonical homes; documents the `0.5.0` removal target.
+
+  ## CLAUDE.md monorepo layout
+  - `playwright/` entry now describes the canonical
+    `page.screenshot({ annot })` patch + `annotSourceResolvers`
+    extension hook. Version bumped to 0.4.0.
+  - `product-docs/` entry mentions the `productDocs` fixture
+    rename + the MDX-aware resolver registration via the hook
+    registry. Version bumped to 0.3.0.
+  - `product-docs-astro/` entry calls out the deprecated
+    `/playwright` re-export shim + 0.5.0 removal target.
+    `@playwright/test` no longer a peer dep. Version bumped to
+    0.3.0.
+
+  ## Plan archive
+  - `docs/plans/playwright-screenshot-fixture-relayer.md` →
+    `docs/plans/_done/playwright-screenshot-fixture-relayer.md`.
+    Status header switched to `Done` with the four landing PRs
+    enumerated. Internal `./_done/...` link paths updated to
+    `./...` (the plan is itself inside `_done/` now).
+  - `docs/plans/README.md` — removed the active entry, added a
+    "Recently landed plans" row pointing at the archived plan
+    with a multi-phase summary covering all four landing PRs.
+  - `docs/plans/living-spec-authoring-roadmap.md` — three link
+    references updated to point at the archived path; the "How
+    this relates" line switched from "Already Draft" to "Landed
+    2026-05-22 (PRs #962 / #963 / #964 / #966)".
+
+  No source code changes; verified via `pnpm -r typecheck`,
+  `pnpm test`, `pnpm lint` regardless to confirm the doc/comment
+  edits parse cleanly.
+
+- Updated dependencies [f979374]
+- Updated dependencies [5778902]
+- Updated dependencies [96e7625]
+- Updated dependencies [85d40e6]
+  - @ingcreators/annot-playwright@0.4.0
+  - @ingcreators/annot-product-docs@0.3.0
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -89,41 +89,30 @@ 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)
+## Migration — Playwright fixture moved
 
-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:
+> The Playwright fixture that previously lived at
+> `@ingcreators/annot-product-docs-astro/playwright` moved out
+> of this package as part of
+> [`docs/plans/_done/playwright-screenshot-fixture-relayer.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/_done/playwright-screenshot-fixture-relayer.md)
+> (Phases 1–4). Code authoring a Playwright spec should pick
+> one of the two canonical homes:
 
-```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.
+| Use case | Import |
+|---|---|
+| Living-product-docs tour (MDX-linked `annot.mdx`) | `import { test } from "@ingcreators/annot-product-docs";` |
+| VRT specs / marketing screenshots / AI agent flows (no MDX) | `import { test } from "@ingcreators/annot-playwright";` |
+
+The `@ingcreators/annot-product-docs-astro/playwright` subpath
+remains as a deprecated re-export so existing callers still
+compile; it emits a `DeprecationWarning` at import time and
+will be removed in `@ingcreators/annot-product-docs-astro@0.5.0`.
+`@playwright/test` is no longer a peer dep of this package —
+the canonical homes carry the relationship now.
+
+`renderAnnotatedScreen` (the Astro Image Service) lives on as
+the build-time renderer for the `<Screen>` block; this section
+isn't going anywhere.
 
 ## Tier
 

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>