proto-plugin 0.1.1 → 0.1.3

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>
+  );
+}

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

@@ -584,28 +584,20 @@ function CommentCard<TState>({
         <div className={cardStyles.screenshotInner}>
           <div
             className={cardStyles.screenshot}
-            style={
-              isSidebarLayout
-                ? undefined
-                : { aspectRatio: aspectRatio ?? "16 / 9" }
-            }
+            style={{
+              aspectRatio: aspectRatio ?? "16 / 9",
+              ...(isSidebarLayout ? { maxHeight: 220 } : {}),
+            }}
           >
             {annotation.screenshot ? (
               <>
                 <img
                   src={annotation.screenshot}
                   alt={annotation.comment}
-                  className={
-                    isSidebarLayout ? cardStyles.screenshotImgSidebar : undefined
-                  }
-                  style={
-                    isSidebarLayout
-                      ? { objectPosition: screenshotObjectPosition }
-                      : {
-                          ...s.screenshotImg,
-                          objectPosition: screenshotObjectPosition,
-                        }
-                  }
+                  style={{
+                    ...s.screenshotImg,
+                    objectPosition: screenshotObjectPosition,
+                  }}
                 />
                 {viewportBox && viewport && (
                   <div

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

@@ -3,14 +3,9 @@
 import { countUnresolvedAnnotations } from "../core/annotation-status";
 import { useCommentStore } from "../react/CommentProvider";
 import { CommentHeaderCount } from "./CommentHeaderCount";
+import { CommentModeToggleButton } from "./CommentModeToggleButton";
 import { CommentsGrid } from "./CommentsGrid";
-import {
-  SIDEBAR_ICON_BUTTON_CLASS,
-  Sidebar,
-} from "@prototype/components/platform-ui/sidebar";
-import { IconButton } from "@prototype/components/platform-ui/icon-button";
-import { cn } from "@prototype/lib/utils";
-import { MessageSquarePlus } from "lucide-react";
+import { Sidebar } from "@prototype/components/platform-ui/sidebar";
 
 type CommentsSidebarProps = {
   open: boolean;
@@ -47,19 +42,10 @@ export function CommentsSidebar({
       widthCssVar="--comments-sidebar-width"
       headerActions={
         onToggleCommentMode ? (
-          <IconButton
-            type="button"
+          <CommentModeToggleButton
+            isActive={isCommentModeActive}
             onClick={onToggleCommentMode}
-            onMouseDown={(event) => event.preventDefault()}
-            aria-label={isCommentModeActive ? "Exit comment mode" : "Add comment"}
-            aria-pressed={isCommentModeActive}
-            className={cn(
-              SIDEBAR_ICON_BUTTON_CLASS,
-              isCommentModeActive && "bg-accent text-accent-foreground",
-            )}
-          >
-            <MessageSquarePlus size={16} strokeWidth={2} />
-          </IconButton>
+          />
         ) : null
       }
     >

package/src/lib/prototype-comments/ui/capture-styles.module.scss

@@ -870,9 +870,13 @@
 }
 
 :global(html[data-comments-sidebar-open]) .markersLayer,
+:global(html[data-prototype-review-sidebar-open]) .markersLayer,
 :global(html[data-comments-sidebar-open]) .fixedMarkersLayer,
+:global(html[data-prototype-review-sidebar-open]) .fixedMarkersLayer,
 :global(html[data-comments-sidebar-open]) .overlay,
-:global(html[data-comments-sidebar-open]) .targetHighlightLayer {
+:global(html[data-prototype-review-sidebar-open]) .overlay,
+:global(html[data-comments-sidebar-open]) .targetHighlightLayer,
+:global(html[data-prototype-review-sidebar-open]) .targetHighlightLayer {
   right: var(--comments-sidebar-width, 400px);
 }
 

package/src/lib/prototype-comments/ui/comments-grid-card.module.scss

@@ -42,13 +42,6 @@
   transition: border-color 0.2s cubic-bezier(0.215, 0.61, 0.355, 1);
 }
 
-.screenshotImgSidebar {
-  display: block;
-  width: 100%;
-  height: auto;
-  max-height: 220px;
-}
-
 .cardCondensed .screenshot {
   border-bottom-color: transparent;
 }

package/src/lib/prototypes/build-design-exploration-renderers.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+
+import type {
+  DesignExplorationBaselineOption,
+  DesignExplorationVariantOption,
+} from "./design-exploration-types";
+import { getDesignExplorationDisplayOptions } from "./design-exploration-types";
+
+/**
+ * Builds a renderer entry for every design exploration option. Prefer this over
+ * hand-rolled `Object.fromEntries` maps so each variant gets a preview and new
+ * options cannot silently return `null`.
+ */
+export function buildDesignExplorationRenderers<TVariant extends string>(
+  options: readonly DesignExplorationVariantOption<TVariant>[],
+  renderVariant: (variant: TVariant) => ReactNode,
+  baseline?: DesignExplorationBaselineOption<TVariant>,
+): Record<TVariant, () => ReactNode> {
+  const displayOptions = baseline
+    ? getDesignExplorationDisplayOptions([...options], baseline)
+    : options;
+  const renderers = {} as Record<TVariant, () => ReactNode>;
+
+  for (const option of displayOptions) {
+    const variant = option.value as TVariant;
+    renderers[variant] = () => {
+      const node = renderVariant(variant);
+
+      if (process.env.NODE_ENV !== "production" && isEmptyRendererOutput(node)) {
+        console.warn(
+          `[prototype] Design exploration renderer for "${variant}" returned no preview content.`,
+        );
+      }
+
+      return node;
+    };
+  }
+
+  return renderers;
+}
+
+function isEmptyRendererOutput(node: ReactNode): boolean {
+  return node == null || node === false;
+}

package/src/lib/prototypes/changelog-description-prompt.ts

@@ -0,0 +1,58 @@
+export function buildChangelogDescriptionPrompt({
+  slug,
+  description,
+  origin = "http://localhost:3003",
+}: {
+  slug: string;
+  description: string;
+  origin?: string;
+}): string {
+  const prototypeUrl = `${origin}/prototypes/${slug}`;
+  const trimmed = description.trim();
+
+  const lines = [
+    `Update the "${slug}" prototype to match the following change log overview.`,
+    "",
+    "## Description",
+  ];
+
+  if (trimmed) {
+    lines.push(trimmed);
+  } else {
+    lines.push(
+      "Summarize what changed in this prototype and why:",
+      "- What changed:",
+      "- Why:",
+    );
+  }
+
+  lines.push(
+    "",
+    "## Prototype",
+    `- Slug: \`${slug}\``,
+    `- Preview: ${prototypeUrl}`,
+    `- Work in: \`src/prototypes/${slug}/\``,
+    "",
+    "## Instructions",
+    "1. Review the overview and anchored changelog entries in the prototype review sidebar.",
+    "2. Apply any missing updates so the prototype matches the described changes.",
+    "3. Do not persist this overview in KV — it is prompt-only.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildChangelogDescriptionCopyText({
+  slug,
+  description,
+  origin,
+}: {
+  slug: string;
+  description: string;
+  origin?: string;
+}): string {
+  const prompt = buildChangelogDescriptionPrompt({ slug, description, origin });
+  const trimmed = description.trim();
+  if (!trimmed) return prompt;
+  return `${trimmed}\n\n---\n\n${prompt}`;
+}