proto-plugin 0.1.0 → 0.1.2

package/src/lib/copy-text-with-attachments.ts

@@ -0,0 +1,35 @@
+import { toast } from "sonner";
+
+function copyTextWithExecCommand(text: string): boolean {
+  try {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.left = "-9999px";
+    textarea.style.top = "0";
+    document.body.appendChild(textarea);
+    textarea.select();
+    const ok = document.execCommand("copy");
+    document.body.removeChild(textarea);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyTextWithAttachments(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    if (copyTextWithExecCommand(text)) {
+      return true;
+    }
+
+    toast.error("Copy error", {
+      description: "Failed to copy prompt to clipboard",
+    });
+    return false;
+  }
+}

package/src/lib/format-source-directory-name.ts

@@ -0,0 +1,12 @@
+/** Last path segment of SOURCE_PATH for gallery chrome, e.g. `/path/to/proto-site` → `proto-site`. */
+export function formatSourceDirectoryName(
+  sourcePath: string | undefined,
+): string | undefined {
+  const trimmed = sourcePath?.trim();
+  if (!trimmed) return undefined;
+
+  const normalized = trimmed.replace(/[/\\]+$/, "");
+  const segments = normalized.split(/[/\\]/);
+  const name = segments.at(-1);
+  return name || undefined;
+}

package/src/lib/platform-ui/sidebar-interactive-cursor.ts

@@ -0,0 +1,19 @@
+/** Interactive targets inside review/platform sidebars that should show pointer. */
+export const SIDEBAR_INTERACTIVE_POINTER_SELECTOR =
+  ":is(button:not(:disabled), [role='button']:not([aria-disabled='true']), a[href], summary, label:has([role='switch']), label:has(input[type='checkbox']))";
+
+export const SIDEBAR_ROOT_SELECTORS = [
+  "[data-prototype-review-sidebar]",
+  "[data-comments-sidebar]",
+  "[data-platform-sidebar]",
+  "#prototype-comments-sidebar-root",
+] as const;
+
+export function buildSidebarInteractivePointerCss(options?: {
+  important?: boolean;
+}): string {
+  const suffix = options?.important ? " !important" : "";
+  return SIDEBAR_ROOT_SELECTORS.map(
+    (root) => `${root} ${SIDEBAR_INTERACTIVE_POINTER_SELECTOR}`,
+  ).join(",\n") + ` { cursor: pointer${suffix}; }`;
+}

package/src/lib/pr-split/build-pr-split-plan-prompt.ts

@@ -0,0 +1,81 @@
+export type PrSplitPlanPromptOptions = {
+  slug: string;
+  origin?: string;
+  sourceRepo?: string;
+  sourceWorkPath?: string;
+};
+
+export function buildPrSplitPlanPrompt({
+  slug,
+  origin = "http://localhost:1985",
+  sourceRepo = "calcom/cal.diy",
+  sourceWorkPath = "apps/web",
+}: PrSplitPlanPromptOptions): string {
+  const prototypePath = `src/prototypes/${slug}/`;
+  const configPath = `${prototypePath}_components/pr-split-config.ts`;
+  const wireframesPath = `${prototypePath}_components/pr-split-wireframes.tsx`;
+  const previewUrl = `${origin}/prototypes/${slug}?reviewPanel=spec`;
+
+  return [
+    `Create a PR split spec for the \`${slug}\` prototype. **First identify everything that changed**, then propose a merge-ordered PR plan and implement the spec in this repo.`,
+    "",
+    "## Phase 1 — Audit what changed",
+    "",
+    "1. Read the prototype at `" + prototypePath + "` — especially `index.tsx`, any `*-preview-states.ts`, all `*-design-exploration-config.tsx` files, mock data, and `component-ids.ts`.",
+    "2. For each design exploration, compare the **baseline** option (marked **Original** in the brief) to the **default variant** in code (`DEFAULT_*_VARIANT` constants). Baselines = production / pre-exploration UI; defaults = chosen shipping direction.",
+    "3. Compare against production in the source app (`SOURCE_PATH` / `source/` symlink, repo `" + sourceRepo + "`). Find the real page under `" + sourceWorkPath + "` and list layout, behavior, and data-model deltas.",
+    "4. Run `git log` and `git diff` on `" + prototypePath + "` to capture the full change history (including uncommitted work).",
+    "5. Read preview states in `*-preview-states.ts` — each distinct reviewer mode may map to a PR slice.",
+    "6. Note explorations that should **stay in the design brief only** (alternate layout or entry-point variants not chosen for shipping).",
+    "",
+    "## Phase 2 — Plan the PR breakdown",
+    "",
+    "Propose **3–7 small, merge-ordered PRs** for `" + sourceRepo + "`. For each PR, define:",
+    "",
+    "- `order`, `title`, `description` (2–3 sentences of source-repo work)",
+    "- `size` (`Small` | `Medium` | `Large`)",
+    "- `targetId` — one registered id from `component-ids.ts`",
+    "- `wireframeId` — key for a full-page schematic wireframe renderer",
+    "- `liveState` — restores the prototype preview for that slice",
+    "- Dependencies on earlier PRs in the series",
+    "",
+    "Grouping guidance:",
+    "- Ship data / filter logic before UI entry points that depend on it",
+    "- Keep the primary layout change as its own PR",
+    "- Empty states, modals, and polish can follow once foundation PRs land",
+    "- Do not bundle unrelated design-brief alternates into shipping PRs",
+    "",
+    "Present the plan as a numbered list with a short dependency diagram before implementing.",
+    "",
+    "## Phase 3 — Implement the PR split spec (this repo)",
+    "",
+    "Follow `packages/prototype/AGENTS.md` → **PR split specs**:",
+    "",
+    "1. Create `" + configPath + "` with `PR_SPLIT_CONFIG` and `PR_SPLIT_ENTRIES`",
+    "   - `slug: \"" + slug + "\"`",
+    "   - `sourceRepo: \"" + sourceRepo + "\"`, `sourceWorkPath: \"" + sourceWorkPath + "\"`",
+    "   - `writeEntryToSearchParams` restores each entry's `liveState`",
+    "   - `scopeNote` guardrail: do not ship unchosen design-brief variants",
+    "2. Create `" + wireframesPath + "` — full-page schematic wireframes (see **Wireframe rules** below)",
+    "3. Wire `" + prototypePath + "index.tsx` — parse/sync `?prSplit=`, call `setSpecContent(<PrototypeSpecPanelContent ...>)`, `handlePrNavigate` with `focusShareTarget`",
+    "4. Update `component-ids.ts` — add `spec-panel-content`, wireframe ids, etc.",
+    "5. Verify each PR card restores the correct prototype state and highlights the right component",
+    "",
+    "### Wireframe rules (mandatory)",
+    "",
+    "Each PR card preview must show the **full prototype page shell** — sidebar, header/toolbar, and main content area as reviewers see them in the live preview. Do **not** draw cropped excerpts, zoomed-in component slices, or short strips that only show the changed region.",
+    "",
+    "- Scaffold every wireframe from the prototype's real page layout (match the shell layout component)",
+    "- Use low-fidelity `Wire` blocks; apply `PR_TARGET_HIGHLIGHT_BORDER` / `PR_TARGET_HIGHLIGHT_FILL` only on the PR target",
+    "- Fill the card preview area: wrap the wireframe root in `PR_SPLIT_WIREFRAME_FRAME_CLASS` (`aspect-video w-full overflow-hidden`) so the schematic reads as a full screen, not a tiny excerpt",
+    "- The highlight shows where the slice lands on the page; surrounding chrome provides context",
+    "",
+    "Prototype preview: " + previewUrl,
+    "",
+    "After the spec is wired, summarize the final PR sequence for the user. Do not open source PRs until the plan is approved.",
+  ].join("\n");
+}
+
+export function buildPrSplitPlanCopyText(options: PrSplitPlanPromptOptions): string {
+  return buildPrSplitPlanPrompt(options);
+}

package/src/lib/pr-split/pr-split-highlight.ts

@@ -4,3 +4,6 @@ export const PR_TARGET_HIGHLIGHT_BORDER =
 
 export const PR_TARGET_HIGHLIGHT_FILL =
   "color-mix(in srgb, var(--prototype-comment-color-blue) 6%, transparent)";
+
+/** Root wrapper for PR split wireframes — full-page schematic, not a cropped excerpt. */
+export const PR_SPLIT_WIREFRAME_FRAME_CLASS = "aspect-video w-full overflow-hidden";

package/src/lib/prototype-comments/core/annotation-target.ts

@@ -1,4 +1,5 @@
 import { getElementClasses } from "./element-identification";
+import { getPrototypeScreenshotRoot } from "@prototype/lib/tool-portal";
 
 export const PROTOTYPE_TARGET_ATTR = "data-prototype-target";
 const PROTOTYPE_SCREENSHOT_ROOT = "[data-prototype-screenshot]";
@@ -37,9 +38,17 @@ export function getCommentsSidebarWidth(): number {
 }
 
 export function getCommentsSidebarInset(): number {
-  if (!document.documentElement.hasAttribute("data-comments-sidebar-open")) return 0;
-  // Inline sidebar already shrinks the prototype content area — no coordinate offset needed.
-  if (document.documentElement.hasAttribute("data-comments-sidebar-inline")) return 0;
+  const isOpen =
+    document.documentElement.hasAttribute("data-comments-sidebar-open") ||
+    document.documentElement.hasAttribute("data-prototype-review-sidebar-open");
+  if (!isOpen) return 0;
+
+  const isInline =
+    document.documentElement.hasAttribute("data-comments-sidebar-inline") ||
+    document.documentElement.hasAttribute("data-prototype-review-sidebar-inline") ||
+    getPrototypeScreenshotRoot() != null;
+  if (isInline) return 0;
+
   return getCommentsSidebarWidth();
 }
 

package/src/lib/prototype-comments/core/comment-capture-blocked.ts

@@ -1,4 +1,5 @@
 import { closestCrossingShadow } from "./element-identification";
+import { buildSidebarInteractivePointerCss } from "@prototype/lib/platform-ui/sidebar-interactive-cursor";
 
 /** DOM regions where comment capture must not attach (plugin chrome, not prototype UI). */
 export const COMMENT_CAPTURE_BLOCKED_SELECTORS = [
@@ -21,6 +22,28 @@ export function isCommentCaptureBlockedTarget(target: HTMLElement): boolean {
   );
 }
 
+/** Plugin chrome where interacting should exit comment mode (not the prototype canvas). */
+export const COMMENT_MODE_CHROME_SELECTORS = [
+  "[data-prototype-review-trigger]",
+  "[data-prototype-review-sidebar]",
+  "[data-prototype-review-panel]",
+  "[data-feedback-toolbar]",
+  "[data-comment-capture-toolbar]",
+  "[data-comments-sidebar]",
+  "#prototype-comments-sidebar-root",
+] as const;
+
+export const COMMENT_MODE_TOGGLE_SELECTOR = "[data-prototype-comment-mode-toggle]";
+
+export function isCommentModeChromeInteraction(target: HTMLElement): boolean {
+  if (closestCrossingShadow(target, COMMENT_MODE_TOGGLE_SELECTOR) != null) {
+    return false;
+  }
+  return COMMENT_MODE_CHROME_SELECTORS.some(
+    (selector) => closestCrossingShadow(target, selector) != null,
+  );
+}
+
 /** CSS :not() chain for descendants that should not receive comment-mode crosshair. */
 export function buildCommentCaptureCursorExclusionCss(): string {
   return COMMENT_CAPTURE_BLOCKED_SELECTORS.flatMap((selector) => [
@@ -43,5 +66,6 @@ export function buildCommentCaptureCursorStyles(): string {
     ${blockedCursorReset} {
       cursor: auto !important;
     }
+    ${buildSidebarInteractivePointerCss({ important: true })}
   `;
 }

package/src/lib/prototype-comments/core/screenshot.ts

@@ -11,6 +11,7 @@
 // Cache the import result so we only try once
 let _domCaptureModule: {
   domToCanvas: (node: Node, options?: Record<string, unknown>) => Promise<HTMLCanvasElement>;
+  domToJpeg: (node: Node, options?: Record<string, unknown>) => Promise<string>;
 } | null | undefined; // null = tried and failed, undefined = not tried yet
 
 async function getDomCapture() {
@@ -36,6 +37,10 @@ import {
   getCommentsSidebarInset,
   getPrototypeScrollContainer,
 } from "./annotation-target";
+import {
+  getPrototypeScreenshotRoot,
+  PROTOTYPE_COMMENTS_SIDEBAR_ROOT_ID,
+} from "@prototype/lib/tool-portal";
 import type { CaptureViewport } from "./types";
 
 type CaptureUiRestore = {
@@ -43,7 +48,7 @@ type CaptureUiRestore = {
 };
 
 /**
- * Hide feedback overlays during capture while leaving the comments sidebar untouched.
+ * Hide feedback overlays and the comments sidebar during capture.
  */
 async function prepareDomForCapture(): Promise<CaptureUiRestore> {
   // Map ensures each element is hidden/restored once. The review toolbar matches
@@ -52,7 +57,6 @@ async function prepareDomForCapture(): Promise<CaptureUiRestore> {
 
   const hideElement = (el: Element) => {
     const html = el as HTMLElement;
-    if (html.closest("[data-comments-sidebar]")) return;
     if (hidden.has(html)) return;
     hidden.set(html, html.style.visibility);
     html.style.visibility = "hidden";
@@ -66,18 +70,16 @@ async function prepareDomForCapture(): Promise<CaptureUiRestore> {
     "[data-annotation-marker]",
     "[data-annotation-popup]",
     "[data-comment-capture-overlay]",
+    `#${PROTOTYPE_COMMENTS_SIDEBAR_ROOT_ID}`,
+    "[data-comments-sidebar]",
+    "[data-prototype-review-sidebar]",
   ];
 
   for (const selector of captureUiSelectors) {
     document.querySelectorAll(selector).forEach(hideElement);
   }
 
-  // Hide standalone overlay roots (e.g. restore overlay), but keep the comments sidebar visible
-  // so cropSidebarFromCanvas can still trim it from the captured image.
-  document.querySelectorAll("[data-prototype-comment-root]").forEach((root) => {
-    if (root.querySelector("[data-comments-sidebar]")) return;
-    hideElement(root);
-  });
+  document.querySelectorAll("[data-prototype-comment-root]").forEach(hideElement);
 
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
   await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
@@ -111,6 +113,31 @@ function cropSidebarFromCanvas(
   return cropped;
 }
 
+function drawCanvasPreservingAspect(
+  ctx: CanvasRenderingContext2D,
+  source: HTMLCanvasElement,
+  destWidth: number,
+  destHeight: number,
+) {
+  const targetAspect = destWidth / destHeight;
+  const sourceAspect = source.width / source.height;
+
+  let sx = 0;
+  let sy = 0;
+  let sw = source.width;
+  let sh = source.height;
+
+  if (sourceAspect > targetAspect) {
+    sw = source.height * targetAspect;
+    sx = (source.width - sw) / 2;
+  } else if (sourceAspect < targetAspect) {
+    sh = source.width / targetAspect;
+    sy = 0;
+  }
+
+  ctx.drawImage(source, sx, sy, sw, sh, 0, 0, destWidth, destHeight);
+}
+
 export type ViewportScreenshotResult = {
   dataUrl: string;
   captureViewport: CaptureViewport;
@@ -129,33 +156,49 @@ export async function captureViewportScreenshot(
     return null;
   }
 
-  const sidebarInset = getCommentsSidebarInset();
-  const inlineContent = document.querySelector("[data-prototype-screenshot]");
-  const isInlineSidebar = document.documentElement.hasAttribute("data-comments-sidebar-inline");
+  const screenshotRoot = getPrototypeScreenshotRoot();
+  const sidebarInset = screenshotRoot ? 0 : getCommentsSidebarInset();
   const { restore } = await prepareDomForCapture();
 
   try {
-    const captureTarget = isInlineSidebar && inlineContent instanceof HTMLElement
-      ? inlineContent
-      : document.documentElement;
-
-    const targetRect = captureTarget.getBoundingClientRect();
-    const viewportWidth = isInlineSidebar && inlineContent instanceof HTMLElement
-      ? targetRect.width
+    const captureTarget = screenshotRoot ?? document.documentElement;
+    const viewportWidth = screenshotRoot
+      ? screenshotRoot.clientWidth
       : window.innerWidth;
-    const viewportHeight = isInlineSidebar && inlineContent instanceof HTMLElement
-      ? targetRect.height
+    const viewportHeight = screenshotRoot
+      ? screenshotRoot.clientHeight
       : window.innerHeight;
     const contentWidth = Math.max(1, viewportWidth - sidebarInset);
     const maxWidth = 1200;
-    const scale = Math.min(1, maxWidth / viewportWidth);
-    const outW = Math.round(viewportWidth * scale);
+    const scale = Math.min(1, maxWidth / contentWidth);
+    const scrollContainer = getPrototypeScrollContainer();
+    const captureViewport: CaptureViewport = {
+      width: screenshotRoot ? viewportWidth : contentWidth,
+      height: viewportHeight,
+      scrollY: window.scrollY,
+      scrollTop: scrollContainer?.scrollTop ?? 0,
+    };
+
+    if (screenshotRoot) {
+      const dataUrl = await mod.domToJpeg(captureTarget, {
+        backgroundColor: "#ffffff",
+        timeout: 5000,
+        width: viewportWidth,
+        height: viewportHeight,
+        quality,
+        scale,
+      });
+
+      return { dataUrl, captureViewport };
+    }
+
+    const outW = Math.round(contentWidth * scale);
     const outH = Math.round(viewportHeight * scale);
 
     const domCanvas = await mod.domToCanvas(captureTarget, {
       backgroundColor: "#ffffff",
       timeout: 5000,
-      width: viewportWidth,
+      width: window.innerWidth,
       height: viewportHeight,
     });
 
@@ -165,18 +208,12 @@ export async function captureViewportScreenshot(
     const ctx = canvas.getContext("2d");
     if (!ctx) return null;
 
-    ctx.drawImage(domCanvas, 0, 0, outW, outH);
+    drawCanvasPreservingAspect(ctx, domCanvas, outW, outH);
 
     const cropped = cropSidebarFromCanvas(canvas, sidebarInset, scale);
-    const scrollContainer = getPrototypeScrollContainer();
     return {
       dataUrl: cropped.toDataURL("image/jpeg", quality),
-      captureViewport: {
-        width: contentWidth,
-        height: viewportHeight,
-        scrollY: window.scrollY,
-        scrollTop: scrollContainer?.scrollTop ?? 0,
-      },
+      captureViewport,
     };
   } catch (err) {
     console.warn("[prototype-comments] Viewport capture failed:", err);

package/src/lib/prototype-comments/core/storage.ts

@@ -1,3 +1,4 @@
+import { COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE } from "@prototype/lib/prototypes/comment-storage-setup-prompt";
 import { isValidAnnotation } from "./validation";
 
 export interface CommentStorageAdapter<T extends { id: string }> {
@@ -30,9 +31,7 @@ export function createRemoteStorageAdapter<T extends { id: string }>(
     );
 
     if (response.status === 503) {
-      throw new CommentStorageError(
-        "Comment storage is not configured. Set Upstash Redis env vars.",
-      );
+      throw new CommentStorageError(COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE);
     }
 
     if (!response.ok) {
@@ -48,9 +47,7 @@ export function createRemoteStorageAdapter<T extends { id: string }>(
       const response = await fetch(listUrl);
 
       if (response.status === 503) {
-        throw new CommentStorageError(
-          "Comment storage is not configured. Set Upstash Redis env vars.",
-        );
+        throw new CommentStorageError(COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE);
       }
 
       if (!response.ok) {

package/src/lib/prototype-comments/core/types.ts

@@ -66,6 +66,8 @@ export type CommentStore<TState> = {
   slug: string;
   annotations: CommentAnnotation<TState>[];
   storageReady: boolean;
+  /** False when server env vars are missing; null while checking. */
+  storageConfigured: boolean | null;
   storageError: string | null;
   addAnnotation: (
     fields: Omit<CommentAnnotation<TState>, "interactionState">,

package/src/lib/prototype-comments/hooks/useLayoutShift.ts

@@ -17,7 +17,8 @@ export function useLayoutShift(): number {
       for (const mutation of mutations) {
         if (
           mutation.type === "attributes" &&
-          mutation.attributeName === "data-comments-sidebar-open"
+          (mutation.attributeName === "data-comments-sidebar-open" ||
+            mutation.attributeName === "data-prototype-review-sidebar-open")
         ) {
           bump();
           break;
@@ -26,7 +27,13 @@ export function useLayoutShift(): number {
     });
     mutationObserver.observe(document.documentElement, {
       attributes: true,
-      attributeFilter: ["data-comments-sidebar-open", "data-comments-sidebar-resizing", "style"],
+      attributeFilter: [
+        "data-comments-sidebar-open",
+        "data-prototype-review-sidebar-open",
+        "data-comments-sidebar-resizing",
+        "data-prototype-review-sidebar-resizing",
+        "style",
+      ],
     });
 
     const handleTransitionEnd = (event: TransitionEvent) => {

package/src/lib/prototype-comments/react/CommentCaptureToolbar.tsx

@@ -53,6 +53,7 @@ import { getRootAnnotations, resolveThreadRootId } from "../core/comment-threads
 import {
   buildCommentCaptureCursorStyles,
   isCommentCaptureBlockedTarget,
+  isCommentModeChromeInteraction,
 } from "../core/comment-capture-blocked";
 import { closestCrossingShadow } from "../core/element-identification";
 import { injectCaptureColorTokens } from "../core/capture-theme";
@@ -209,6 +210,13 @@ export function CommentCaptureToolbar<TState = unknown>({
   const [scrollY, setScrollY] = useState(0);
 
   const isFeedbackActive = isGiveAMomentMode;
+  const isChangelogModeActive =
+    isGiveAMomentMode &&
+    integratedReview &&
+    review?.captureChannel === "changelog";
+  const isCommentModeActive =
+    isGiveAMomentMode &&
+    (!integratedReview || review?.captureChannel === "comment");
   const annotationTargetOptions = useMemo(() => {
     if (typeof resolveTargetOptions === "function") {
       return resolveTargetOptions();
@@ -354,6 +362,18 @@ export function CommentCaptureToolbar<TState = unknown>({
     setIsGiveAMomentMode((active) => !active);
   }, [integratedReview, review]);
 
+  const exitCommentMode = useCallback(() => {
+    setPendingMultiSelectElements([]);
+    setPendingAnnotation(null);
+    setPendingExiting(false);
+    setHoverInfo(null);
+    setIsGiveAMomentMode(false);
+    modifiersHeldRef.current = { cmd: false, shift: false };
+    if (document.activeElement instanceof HTMLElement) {
+      document.activeElement.blur();
+    }
+  }, []);
+
   const cancelAnnotation = useCallback(() => {
     setPendingExiting(true);
     originalSetTimeout(() => {
@@ -983,6 +1003,28 @@ export function CommentCaptureToolbar<TState = unknown>({
     createMultiSelectPendingAnnotation,
   ]);
 
+  useEffect(() => {
+    if (!isCommentModeActive) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      exitCommentMode();
+    };
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = (event.composedPath()[0] || event.target) as HTMLElement;
+      if (!isCommentModeChromeInteraction(target)) return;
+      exitCommentMode();
+    };
+
+    document.addEventListener("keydown", handleKeyDown, true);
+    document.addEventListener("pointerdown", handlePointerDown, true);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown, true);
+      document.removeEventListener("pointerdown", handlePointerDown, true);
+    };
+  }, [exitCommentMode, isCommentModeActive]);
+
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       const isTyping =
@@ -1000,7 +1042,7 @@ export function CommentCaptureToolbar<TState = unknown>({
           return;
         }
         if (pendingAnnotation) return;
-        if (isGiveAMomentMode) {
+        if (isChangelogModeActive) {
           setIsGiveAMomentMode(false);
           e.preventDefault();
           if (document.activeElement instanceof HTMLElement) {
@@ -1028,7 +1070,7 @@ export function CommentCaptureToolbar<TState = unknown>({
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
   }, [
-    isGiveAMomentMode,
+    isChangelogModeActive,
     pendingAnnotation,
     pendingMultiSelectElements.length,
     activateToolbar,
@@ -1052,14 +1094,6 @@ export function CommentCaptureToolbar<TState = unknown>({
     }
   }, [isActive, integratedReview, prototypeSlug]);
 
-  const isChangelogModeActive =
-    isGiveAMomentMode &&
-    integratedReview &&
-    review.captureChannel === "changelog";
-  const isCommentModeActive =
-    isGiveAMomentMode &&
-    (!integratedReview || review.captureChannel === "comment");
-
   const bridgeValue = useMemo<CommentCaptureBridgeValue>(
     () => ({
       onSelect: handleCommentSelect,
@@ -1175,6 +1209,7 @@ export function CommentCaptureToolbar<TState = unknown>({
                           e.stopPropagation();
                           setIsGiveAMomentMode((active) => !active);
                         }}
+                        data-prototype-comment-mode-toggle
                         data-active={isGiveAMomentMode}
                         aria-label={
                           isGiveAMomentMode

package/src/lib/prototype-comments/react/CommentProvider.tsx

@@ -15,6 +15,8 @@ import { captureInteractionState } from "../core/capture";
 import { getRepliesForParent } from "../core/comment-threads";
 import { commentToLiveState } from "../core/restore";
 import { normalizeAnnotationViewport } from "../core/normalize-viewport";
+import { COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE } from "@prototype/lib/prototypes/comment-storage-setup-prompt";
+import { fetchPrototypeStorageStatus, isPrototypeStorageFullyConfigured } from "@prototype/lib/prototypes/prototype-storage-status";
 import { createRemoteStorageAdapter } from "../core/storage";
 import type { CommentAnnotation, CommentStore } from "../core/types";
 
@@ -36,6 +38,7 @@ export function CommentProvider<TState>({
 }: CommentProviderProps<TState>) {
   const [annotations, setAnnotations] = useState<CommentAnnotation<TState>[]>([]);
   const [storageReady, setStorageReady] = useState(false);
+  const [storageConfigured, setStorageConfigured] = useState<boolean | null>(null);
   const [storageError, setStorageError] = useState<string | null>(null);
 
   const getLiveStateRef = useRef(getLiveState);
@@ -70,8 +73,21 @@ export function CommentProvider<TState>({
     async function loadAnnotations() {
       setStorageReady(false);
       setStorageError(null);
+      setStorageConfigured(null);
 
       try {
+        const status = await fetchPrototypeStorageStatus();
+        if (cancelled) return;
+
+        const fullyConfigured = isPrototypeStorageFullyConfigured(status);
+        setStorageConfigured(fullyConfigured);
+
+        if (!fullyConfigured) {
+          setStorageError(COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE);
+          setAnnotations([]);
+          return;
+        }
+
         const stored = await storage.load();
         if (cancelled) return;
         setAnnotations(stored);
@@ -83,6 +99,7 @@ export function CommentProvider<TState>({
             : "Failed to load comments.";
         setStorageError(message);
         setAnnotations([]);
+        setStorageConfigured((current) => current ?? true);
       } finally {
         if (!cancelled) setStorageReady(true);
       }
@@ -254,6 +271,7 @@ export function CommentProvider<TState>({
       slug,
       annotations,
       storageReady,
+      storageConfigured,
       storageError,
       addAnnotation,
       addReply,
@@ -267,6 +285,7 @@ export function CommentProvider<TState>({
       slug,
       annotations,
       storageReady,
+      storageConfigured,
       storageError,
       addAnnotation,
       addReply,

package/src/lib/prototype-comments/ui/CommentModeToggleButton.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { IconButton } from "@prototype/components/platform-ui/icon-button";
+import { cn } from "@prototype/lib/utils";
+import { MessageSquarePlus } from "lucide-react";
+
+type CommentModeToggleButtonProps = {
+  isActive: boolean;
+  onClick: () => void;
+};
+
+export function CommentModeToggleButton({
+  isActive,
+  onClick,
+}: CommentModeToggleButtonProps) {
+  return (
+    <IconButton
+      type="button"
+      variant="chrome"
+      size="icon"
+      onClick={onClick}
+      onMouseDown={(event) => event.preventDefault()}
+      data-prototype-comment-mode-toggle
+      aria-label={isActive ? "Exit comment mode" : "Add comment"}
+      aria-pressed={isActive}
+      className={cn(
+        "size-8 shrink-0",
+        isActive && "bg-accent text-accent-foreground hover:bg-accent/90 hover:text-accent-foreground",
+      )}
+    >
+      <MessageSquarePlus size={16} strokeWidth={2} />
+    </IconButton>
+  );
+}