proto-plugin 0.1.0 → 0.1.2

package/scripts/publish-package.sh

@@ -8,6 +8,8 @@ REGISTRY="https://registry.npmjs.org"
 DRY_RUN=0
 TAG="latest"
 SKIP_VERIFY=0
+SKIP_BUMP=0
+BUMP="patch"
 OTP=""
 
 usage() {
@@ -21,6 +23,8 @@ Options:
   --tag <tag>      npm dist-tag (default: latest)
   --otp <code>     One-time password from your authenticator app
   --skip-verify    Skip pre-publish verification scripts
+  --no-bump        Publish package.json version as-is (fail if already published)
+  --bump <level>   Bump level when current version exists on npm: patch, minor, major (default: patch)
   -h, --help       Show this help message
 
 Examples:
@@ -47,6 +51,21 @@ while [[ $# -gt 0 ]]; do
       SKIP_VERIFY=1
       shift
       ;;
+    --no-bump)
+      SKIP_BUMP=1
+      shift
+      ;;
+    --bump)
+      BUMP="${2:?Missing value for --bump}"
+      case "$BUMP" in
+        patch | minor | major) ;;
+        *)
+          echo "Invalid --bump value: $BUMP (expected patch, minor, or major)" >&2
+          exit 1
+          ;;
+      esac
+      shift 2
+      ;;
     --otp)
       OTP="${2:?Missing value for --otp}"
       shift 2
@@ -99,6 +118,25 @@ fi
 PACKAGE_NAME="$(node -pe "require('./package.json').name")"
 PACKAGE_VERSION="$(node -pe "require('./package.json').version")"
 
+version_is_published() {
+  npm view "${PACKAGE_NAME}@${1}" version --registry "$REGISTRY" >/dev/null 2>&1
+}
+
+ensure_unpublished_version() {
+  local bump_level="$1"
+  while version_is_published "$(node -pe "require('./package.json').version")"; do
+    local current
+    current="$(node -pe "require('./package.json').version")"
+    echo "Version ${current} is already on npm; bumping ${bump_level}..."
+    npm version "$bump_level" --no-git-tag-version
+  done
+}
+
+if [[ "$SKIP_BUMP" -eq 0 ]]; then
+  ensure_unpublished_version "$BUMP"
+  PACKAGE_VERSION="$(node -pe "require('./package.json').version")"
+fi
+
 echo "Publishing ${PACKAGE_NAME}@${PACKAGE_VERSION}"
 echo "Registry: ${REGISTRY}"
 echo "Access: public (unscoped)"
@@ -144,4 +182,7 @@ if [[ "$DRY_RUN" -eq 0 ]]; then
   echo "Install with:"
   echo "  npm install ${PACKAGE_NAME}@${PACKAGE_VERSION}"
   echo "  pnpm add ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+  if [[ "$SKIP_BUMP" -eq 0 ]]; then
+    echo "Commit the version bump in package.json when ready."
+  fi
 fi

package/scripts/verify-prototype-preview-states.mjs

@@ -16,6 +16,40 @@ import {
 const toolRoot = resolveToolRoot(import.meta.url);
 const repoRoot = resolveHostRoot(toolRoot);
 const prototypesDir = path.join(repoRoot, "src/prototypes");
+const prototypeConfigPath = path.join(repoRoot, "prototype.config.ts");
+
+function readPrototypeConfigSource() {
+  if (!fs.existsSync(prototypeConfigPath)) {
+    return null;
+  }
+  return fs.readFileSync(prototypeConfigPath, "utf8");
+}
+
+function prototypeConfigBlockHasStateMapComponent(slug, configSource) {
+  const slugMarker = `slug: "${slug}"`;
+  const slugIndex = configSource.indexOf(slugMarker);
+  if (slugIndex === -1) return false;
+
+  const nextSlugIndex = configSource.indexOf('slug: "', slugIndex + slugMarker.length);
+  const block =
+    nextSlugIndex === -1
+      ? configSource.slice(slugIndex)
+      : configSource.slice(slugIndex, nextSlugIndex);
+
+  return block.includes("stateMapComponent");
+}
+
+function findStateMapPageFiles(slug) {
+  const stateMapPagePath = path.join(prototypesDir, slug, "state-map-page.tsx");
+  return fs.existsSync(stateMapPagePath) ? [stateMapPagePath] : [];
+}
+
+function indexUsesStateCanvasConfig(slug) {
+  const indexPath = path.join(prototypesDir, slug, "index.tsx");
+  if (!fs.existsSync(indexPath)) return false;
+  const source = fs.readFileSync(indexPath, "utf8");
+  return source.includes("setStateCanvasConfig");
+}
 
 function listPrototypeSlugs() {
   return fs
@@ -126,6 +160,29 @@ for (const slug of listPrototypeSlugs()) {
       failed = true;
     }
   }
+
+  const stateMapPageFiles = findStateMapPageFiles(slug);
+  if (stateMapPageFiles.length === 0) {
+    console.error(
+      `[${slug}] Has *-preview-states.ts but no state-map-page.tsx. Add src/prototypes/${slug}/state-map-page.tsx and register stateMapComponent in prototype.config.ts.`,
+    );
+    failed = true;
+  }
+
+  const configSource = readPrototypeConfigSource();
+  if (configSource && !prototypeConfigBlockHasStateMapComponent(slug, configSource)) {
+    console.error(
+      `[${slug}] Has *-preview-states.ts but prototype.config.ts is missing stateMapComponent for this slug.`,
+    );
+    failed = true;
+  }
+
+  if (!indexUsesStateCanvasConfig(slug)) {
+    console.error(
+      `[${slug}] Has *-preview-states.ts but index.tsx does not wire review.setStateCanvasConfig(...).`,
+    );
+    failed = true;
+  }
 }
 
 if (failed) {

package/src/components/platform-ui/controls-panel-select.tsx

@@ -116,21 +116,22 @@ export function ControlsPanelSelect<T extends string>({
   const isMiniPill = appearance === "miniPill";
   const isMenuList = appearance === "menuList";
   const review = usePrototypeReviewOptional();
+  const registerPreviewStates = review?.registerPreviewStates;
   const { commentTheme } = usePrototypeToolTheme();
   const triggerLabel = isMiniPill ? (miniPillLabel ?? activeLabel) : activeLabel;
   const [open, setOpen] = useState(false);
   const triggerRef = useRef<HTMLButtonElement>(null);
 
   useEffect(() => {
-    if (!isMenuList || !review) return;
+    if (!isMenuList || !registerPreviewStates) return;
 
-    review.registerPreviewStates(
+    registerPreviewStates(
       getSelectableOptions(options).map((option) => ({
         id: option.value,
         label: option.label,
       })),
     );
-  }, [isMenuList, options, review]);
+  }, [isMenuList, options, registerPreviewStates]);
 
   const selectSubmenuEntry = useCallback(
     (

package/src/components/platform-ui/prototype-tool-dialog.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogTitle,
+} from "@prototype/components/ui/dialog";
+import { cn } from "@prototype/lib/utils";
+import { X } from "lucide-react";
+import type { ReactNode } from "react";
+
+export const PROTOTYPE_TOOL_MODAL_CLOSE_CLASS =
+  "text-muted-foreground hover:text-foreground inline-flex size-8 shrink-0 items-center justify-center rounded-sm border-0 bg-transparent p-0 opacity-70 transition-opacity duration-200 ease hover:opacity-100 outline-none focus:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-0 disabled:pointer-events-none disabled:opacity-40 disabled:hover:opacity-40 disabled:hover:text-muted-foreground motion-reduce:transition-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+
+export const PROTOTYPE_TOOL_MODAL_TEXTAREA_CLASS =
+  "field-sizing-content min-h-[min(50vh,20rem)] w-full resize-y border-0 bg-transparent px-0 py-0 text-sm leading-relaxed text-foreground shadow-none outline-none placeholder:text-muted-foreground focus-visible:ring-0";
+
+const MODAL_SIZE_CLASS = {
+  md: "w-[min(42rem,calc(100vw-2rem))] max-w-[min(42rem,calc(100vw-2rem))] sm:max-w-[min(42rem,calc(100vw-2rem))]",
+  wide: "w-[min(96rem,calc(100vw-2rem))] max-w-[min(96rem,calc(100vw-2rem))] sm:max-w-[min(96rem,calc(100vw-2rem))]",
+} as const;
+
+function PrototypeToolDialogSeparator() {
+  return (
+    <div
+      className="tool-dialog-separator h-px w-full shrink-0"
+      role="separator"
+      aria-hidden
+    />
+  );
+}
+
+export type PrototypeToolDialogProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+  footer?: ReactNode;
+  footerClassName?: string;
+  headerActions?: ReactNode;
+  size?: keyof typeof MODAL_SIZE_CLASS;
+  bodyClassName?: string;
+  className?: string;
+};
+
+export function PrototypeToolDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  children,
+  footer,
+  footerClassName,
+  headerActions,
+  size = "md",
+  bodyClassName,
+  className,
+}: PrototypeToolDialogProps) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        portalScope="tool"
+        showCloseButton={false}
+        className={cn(
+          "tool-dialog-surface flex max-h-[min(92svh,calc(100%-2rem))] flex-col gap-0 overflow-hidden border-0 p-0",
+          MODAL_SIZE_CLASS[size],
+          className,
+        )}
+      >
+        <div className="flex items-start justify-between gap-3 px-5 py-4">
+          <div className="flex min-w-0 flex-col gap-1">
+            <DialogTitle className="text-base font-medium text-foreground">
+              {title}
+            </DialogTitle>
+            {description ? (
+              <p className="text-sm text-muted-foreground">{description}</p>
+            ) : null}
+          </div>
+          <div className="flex shrink-0 items-center gap-0.5">
+            {headerActions}
+            <DialogClose className={PROTOTYPE_TOOL_MODAL_CLOSE_CLASS}>
+              <X />
+              <span className="sr-only">Close</span>
+            </DialogClose>
+          </div>
+        </div>
+
+        <PrototypeToolDialogSeparator />
+
+        <div
+          className={cn(
+            "flex min-h-0 flex-1 flex-col overflow-y-auto px-5 py-4",
+            bodyClassName,
+          )}
+        >
+          {children}
+        </div>
+
+        {footer ? (
+          <>
+            <PrototypeToolDialogSeparator />
+            <div
+              className={cn(
+                "flex items-center gap-2 px-5 py-3",
+                footerClassName,
+              )}
+            >
+              {footer}
+            </div>
+          </>
+        ) : null}
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/components/platform-ui/sidebar.tsx

@@ -20,11 +20,22 @@ export function clampSidebarWidth(width: number) {
   return Math.min(MAX_SIDEBAR_WIDTH, Math.max(MIN_SIDEBAR_WIDTH, width));
 }
 
+/** e.g. `data-comments-sidebar` + `"open"` → `data-comments-sidebar-open` */
+export function getSidebarStateAttribute(
+  dataAttribute: string,
+  suffix: "open" | "inline" | "resizing",
+): string {
+  const base = dataAttribute.startsWith("data-")
+    ? dataAttribute.slice(5)
+    : dataAttribute;
+  return `data-${base}-${suffix}`;
+}
+
 const SIDEBAR_TITLE_CLASS =
-  "font-display truncate text-sm font-semibold text-[var(--tool-chrome-icon-hover)]";
+  "font-display truncate text-sm font-semibold text-[var(--tool-chrome-text-heading)]";
 
 export const SIDEBAR_ICON_BUTTON_CLASS =
-  "text-[var(--tool-chrome-icon)] hover:bg-[var(--tool-chrome-gray-highlight)] hover:text-[var(--tool-chrome-icon-hover)] focus:outline-none focus-visible:ring-0 focus-visible:ring-offset-0";
+  "cursor-pointer text-[var(--tool-chrome-icon)] hover:bg-[var(--tool-chrome-gray-highlight)] hover:text-[var(--tool-chrome-icon-hover)] focus:outline-none focus-visible:ring-0 focus-visible:ring-offset-0";
 
 type SidebarProps = {
   open: boolean;
@@ -59,6 +70,9 @@ export function Sidebar({
   className,
   overlay = false,
 }: SidebarProps) {
+  const openAttr = getSidebarStateAttribute(dataAttribute, "open");
+  const inlineAttr = getSidebarStateAttribute(dataAttribute, "inline");
+  const resizingAttr = getSidebarStateAttribute(dataAttribute, "resizing");
   const [sidebarWidth, setSidebarWidth] = useState(DEFAULT_SIDEBAR_WIDTH);
   const [isResizing, setIsResizing] = useState(false);
   const resizeStartRef = useRef<{ startX: number; startWidth: number } | null>(
@@ -80,7 +94,9 @@ export function Sidebar({
   );
 
   useEffect(() => {
-    document.documentElement.setAttribute("data-platform-sidebar-inline", "");
+    if (!overlay) {
+      document.documentElement.setAttribute(inlineAttr, "");
+    }
     document.documentElement.style.setProperty(
       widthCssVar,
       `${DEFAULT_SIDEBAR_WIDTH}px`,
@@ -88,22 +104,19 @@ export function Sidebar({
 
     return () => {
       document.documentElement.style.removeProperty(widthCssVar);
-      document.documentElement.removeAttribute("data-platform-sidebar-open");
-      document.documentElement.removeAttribute("data-platform-sidebar-resizing");
-      document.documentElement.removeAttribute("data-platform-sidebar-inline");
+      document.documentElement.removeAttribute(openAttr);
+      document.documentElement.removeAttribute(resizingAttr);
+      document.documentElement.removeAttribute(inlineAttr);
     };
-  }, [widthCssVar]);
+  }, [inlineAttr, openAttr, overlay, resizingAttr, widthCssVar]);
 
   useEffect(() => {
-    document.documentElement.toggleAttribute("data-platform-sidebar-open", open);
-  }, [open]);
+    document.documentElement.toggleAttribute(openAttr, open);
+  }, [open, openAttr]);
 
   useEffect(() => {
-    document.documentElement.toggleAttribute(
-      "data-platform-sidebar-resizing",
-      isResizing,
-    );
-  }, [isResizing]);
+    document.documentElement.toggleAttribute(resizingAttr, isResizing);
+  }, [isResizing, resizingAttr]);
 
   const handleResizeStart = useCallback(
     (event: ReactPointerEvent<HTMLDivElement>) => {
@@ -152,7 +165,7 @@ export function Sidebar({
           : { width: open ? sidebarWidth : 0 }
       }
       className={cn(
-        "flex h-full shrink-0 flex-col overflow-hidden bg-[var(--tool-chrome-ground)] text-[var(--tool-chrome-icon)]",
+        "flex h-full shrink-0 flex-col overflow-hidden bg-[var(--tool-chrome-ground)] text-[var(--tool-chrome-text)]",
         isResizing && "select-none transition-none",
         overlay
           ? "absolute inset-y-0 right-0 shadow-2xl transition-transform duration-200 ease-out"
@@ -226,13 +239,18 @@ type SidebarResizeHandleProps = {
 export function SidebarResizeHandle({
   open,
   sidebarWidth,
+  isResizing,
   onResizeStart,
   onResizeMove,
   onResizeEnd,
 }: SidebarResizeHandleProps) {
   return (
     <div
-      className="absolute top-0 left-[-4px] z-[1] h-full w-2 cursor-col-resize touch-none before:absolute before:top-0 before:left-[3px] before:h-full before:w-0.5 before:bg-transparent before:transition-colors hover:before:bg-border [[data-platform-sidebar-resizing]_&]:before:bg-border"
+      data-resizing={isResizing ? "" : undefined}
+      className={cn(
+        "absolute top-0 left-[-4px] z-[1] h-full w-2 cursor-col-resize touch-none before:absolute before:top-0 before:left-[3px] before:h-full before:w-0.5 before:bg-transparent before:transition-colors hover:before:bg-border data-resizing:before:bg-border",
+        isResizing && "select-none",
+      )}
       onPointerDown={onResizeStart}
       onPointerMove={onResizeMove}
       onPointerUp={onResizeEnd}

package/src/components/prototype-gallery-client.tsx

@@ -1,57 +1,97 @@
 "use client";
 
-import Image from "next/image";
-import Link from "next/link";
-
+import { PrototypeCreatePrototypeModal } from "@prototype/components/prototypes/prototype-create-prototype-modal";
 import type { PrototypeMetadata } from "@prototype/lib/prototypes/prototype-config-types";
 import { screenshotSrc } from "@prototype/lib/prototypes/screenshot-src";
 import { cn } from "@prototype/lib/utils";
+import { Plus } from "lucide-react";
+import Image from "next/image";
+import Link from "next/link";
+import { useState } from "react";
 
 type PrototypeGalleryClientProps = {
   prototypes: PrototypeMetadata[];
   screenshotVersions: Record<string, number>;
 };
 
+const prototypeGalleryTitleClassName =
+  "mt-2 text-sm text-[var(--tool-chrome-text-muted)] transition-colors duration-300 ease-out group-hover:text-[var(--tool-chrome-text-heading)]";
+
+function PrototypeGalleryAddCard({ onClick }: { onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="New prototype"
+      className="group block w-full cursor-pointer text-left"
+    >
+      <div
+        className={cn(
+          "rounded-xl",
+          "shadow-[var(--tool-review-card-shadow)]",
+          "translate-y-0 transition-[translate,box-shadow] duration-300 ease-out will-change-[translate]",
+          "group-hover:-translate-y-1 group-hover:shadow-[var(--tool-review-card-shadow-hover)]",
+        )}
+      >
+        <div className="relative flex aspect-video items-center justify-center overflow-hidden rounded-xl border border-dashed border-[var(--tool-chrome-border)] bg-[var(--tool-chrome-surface)] text-[var(--tool-chrome-text-muted)] transition-colors duration-300 ease-out group-hover:text-[var(--tool-chrome-text-heading)]">
+          <Plus size={20} strokeWidth={2} aria-hidden />
+        </div>
+      </div>
+      <p className={cn(prototypeGalleryTitleClassName, "invisible")} aria-hidden>
+        &nbsp;
+      </p>
+    </button>
+  );
+}
+
 export function PrototypeGalleryClient({
   prototypes,
   screenshotVersions,
 }: PrototypeGalleryClientProps) {
+  const [createModalOpen, setCreateModalOpen] = useState(false);
+
   return (
-    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
-      {prototypes.map((prototype) => (
-        <Link
-          key={prototype.slug}
-          href={`/prototypes/${prototype.slug}`}
-          className="group"
-        >
-          <div
-            className={cn(
-              "rounded-xl",
-              "shadow-[0_1px_3px_0_rgb(0_0_0/0.06)]",
-              "translate-y-0 transition-[translate,box-shadow] duration-300 ease-out will-change-[translate]",
-              "group-hover:-translate-y-1 group-hover:shadow-[0_4px_12px_-4px_rgb(0_0_0/0.10)]",
-            )}
+    <>
+      <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+        <PrototypeGalleryAddCard onClick={() => setCreateModalOpen(true)} />
+        {prototypes.map((prototype) => (
+          <Link
+            key={prototype.slug}
+            href={`/prototypes/${prototype.slug}`}
+            className="group"
           >
-            <div className="border-border bg-background relative aspect-video overflow-hidden rounded-xl border">
-              <Image
-                src={screenshotSrc(
-                  prototype.screenshot,
-                  screenshotVersions[prototype.slug],
-                )}
-                alt={prototype.title}
-                width={1600}
-                height={900}
-                quality={90}
-                sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
-                className="h-full w-full object-cover object-top"
-              />
+            <div
+              className={cn(
+                "rounded-xl",
+                "shadow-[var(--tool-review-card-shadow)]",
+                "translate-y-0 transition-[translate,box-shadow] duration-300 ease-out will-change-[translate]",
+                "group-hover:-translate-y-1 group-hover:shadow-[var(--tool-review-card-shadow-hover)]",
+              )}
+            >
+              <div className="relative aspect-video overflow-hidden rounded-xl border border-[var(--tool-chrome-border)] bg-[var(--tool-chrome-surface)]">
+                <Image
+                  src={screenshotSrc(
+                    prototype.screenshot,
+                    screenshotVersions[prototype.slug],
+                  )}
+                  alt={prototype.title}
+                  width={1600}
+                  height={900}
+                  quality={90}
+                  sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
+                  className="h-full w-full object-cover object-top"
+                />
+              </div>
             </div>
-          </div>
-          <p className="text-sm text-muted-foreground group-hover:text-foreground mt-2 transition-colors duration-300 ease-out">
-            {prototype.title}
-          </p>
-        </Link>
-      ))}
-    </div>
+            <p className={prototypeGalleryTitleClassName}>{prototype.title}</p>
+          </Link>
+        ))}
+      </div>
+
+      <PrototypeCreatePrototypeModal
+        open={createModalOpen}
+        onOpenChange={setCreateModalOpen}
+      />
+    </>
   );
 }

package/src/components/prototypes/design-exploration-variant-preview-shell.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { cn } from "@prototype/lib/utils";
+import type { ReactNode } from "react";
+
+export type DesignExplorationVariantPreviewLayout = "inline" | "overlay";
+
+export type DesignExplorationVariantPreviewShellProps = {
+  /** Use `overlay` when the variant uses absolute positioning on the live page. */
+  layout?: DesignExplorationVariantPreviewLayout;
+  children: ReactNode;
+  className?: string;
+};
+
+/**
+ * Hosts a variant inside the design-brief preview card. Overlay layouts get a
+ * positioned shell so absolutely placed controls remain visible in the sidebar.
+ */
+export function DesignExplorationVariantPreviewShell({
+  layout = "inline",
+  children,
+  className,
+}: DesignExplorationVariantPreviewShellProps) {
+  const isOverlay = layout === "overlay";
+
+  return (
+    <div
+      className={cn(
+        "relative bg-white",
+        isOverlay ? "h-full w-full" : "w-full px-2 py-3",
+        className,
+      )}
+    >
+      {isOverlay ? (
+        <div
+          className="from-muted/25 to-muted/5 pointer-events-none absolute inset-0 bg-gradient-to-b"
+          aria-hidden
+        />
+      ) : null}
+      {children}
+    </div>
+  );
+}

package/src/components/prototypes/prototype-brief-field.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { cn } from "@prototype/lib/utils";
+import type { ComponentPropsWithoutRef } from "react";
+
+/** Shared border/focus styling for prototype brief inputs (gallery modals + review sidebar). */
+export const PROTOTYPE_BRIEF_FIELD_BORDER_CLASS =
+  "border border-border shadow-none outline-none transition-colors focus-visible:border-muted-foreground/40 focus-visible:ring-1 focus-visible:ring-muted-foreground/20 focus-visible:ring-offset-0";
+
+const BRIEF_TEXTAREA_BASE_CLASS =
+  "field-sizing-content w-full resize-y rounded-md bg-transparent px-3 py-2 text-sm leading-relaxed text-foreground placeholder:text-muted-foreground";
+
+export type PrototypeBriefTextareaProps = ComponentPropsWithoutRef<"textarea"> & {
+  minHeightClass?: string;
+};
+
+export function PrototypeBriefTextarea({
+  className,
+  minHeightClass = "min-h-[min(40vh,14rem)]",
+  ...props
+}: PrototypeBriefTextareaProps) {
+  return (
+    <textarea
+      className={cn(
+        BRIEF_TEXTAREA_BASE_CLASS,
+        minHeightClass,
+        PROTOTYPE_BRIEF_FIELD_BORDER_CLASS,
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/prototypes/prototype-change-log-panel.tsx

@@ -20,6 +20,7 @@ import {
 } from "react";
 
 import { PrototypeReferenceDocs } from "./prototype-reference-docs";
+import { PrototypeCommentStorageEmptyState } from "./prototype-comment-storage-empty-state";
 
 const CHANGELOG_SECTION_TITLE_CLASS = "tool-section-label";
 
@@ -105,6 +106,7 @@ export function PrototypeChangeLogPanel({
     updateAnnotation,
     storageError,
     storageReady,
+    storageConfigured,
   } = useCommentStore();
   const { overview, ready: metaReady, error: metaError, setOverview } =
     useChangelogMeta();
@@ -182,6 +184,8 @@ export function PrototypeChangeLogPanel({
         </div>
         {!storageReady ? (
           <p className="text-muted-foreground text-xs">Loading changes…</p>
+        ) : storageConfigured === false ? (
+          <PrototypeCommentStorageEmptyState message={storageError ?? undefined} />
         ) : storageError ? (
           <p className="text-destructive text-xs">{storageError}</p>
         ) : (

package/src/components/prototypes/prototype-comment-storage-empty-state.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import { Button } from "@prototype/components/ui/button";
+import {
+  buildCommentStorageSetupCopyText,
+  COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE,
+} from "@prototype/lib/prototypes/comment-storage-setup-prompt";
+import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
+
+type PrototypeCommentStorageEmptyStateProps = {
+  message?: string;
+  vercelProjectName?: string;
+};
+
+export function PrototypeCommentStorageEmptyState({
+  message = COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE,
+  vercelProjectName,
+}: PrototypeCommentStorageEmptyStateProps) {
+  const { copy, icon, isCopied } = useCopyToClipboard();
+
+  return (
+    <div className="px-1 py-2">
+      <p className="text-sm text-muted-foreground">{message}</p>
+      <div className="mt-3">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8 cursor-pointer gap-1.5"
+          onClick={() => {
+            copy(buildCommentStorageSetupCopyText({ vercelProjectName }));
+          }}
+          aria-label="Copy comment storage setup prompt"
+        >
+          {isCopied ? "Copied prompt" : "Copy setup prompt"}
+          {icon}
+        </Button>
+      </div>
+    </div>
+  );
+}