proto-plugin 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proto-plugin",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -27,6 +27,7 @@
     "./app": "./src/app.ts",
     "./with-prototype": "./src/config/with-prototype.ts",
     "./server": "./src/server.ts",
+    "./ui/*": "./src/components/ui/*.tsx",
     "./styles/globals.css": "./src/styles/globals.css"
   },
   "scripts": {

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

@@ -4,20 +4,20 @@ import { filterAnnotationsByChannel } from "@prototype/lib/prototype-comments/co
 import { useCommentStore } from "@prototype/lib/prototype-comments/react/CommentProvider";
 import { useCommentCaptureBridgeOptional } from "@prototype/lib/prototype-comments/react/CommentCaptureToolbar";
 import { CommentsGrid } from "@prototype/lib/prototype-comments/ui/CommentsGrid";
-import { useChangelogMeta } from "@prototype/lib/prototypes/changelog-meta-context";
+import { buildChangelogDescriptionCopyText } from "@prototype/lib/prototypes/changelog-description-prompt";
 import { usePrototypeReview } from "@prototype/lib/prototypes/prototype-review-context";
+import {
+  prototypeReviewPreferenceKey,
+  usePersistedLocalString,
+} from "@prototype/lib/prototypes/use-persisted-local-state";
 import { ToolbarIconButton } from "@prototype/components/platform-ui/toolbar-icon-button";
+import { Button } from "@prototype/components/ui/button";
 import { Label } from "@prototype/components/ui/label";
 import { Switch } from "@prototype/components/ui/switch";
-import { Plus, Save } from "lucide-react";
+import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
+import { Plus } from "lucide-react";
 import { cn } from "@prototype/lib/utils";
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useState,
-  type ChangeEvent,
-} from "react";
+import { useMemo } from "react";
 
 import { PrototypeReferenceDocs } from "./prototype-reference-docs";
 import { PrototypeCommentStorageEmptyState } from "./prototype-comment-storage-empty-state";
@@ -108,63 +108,63 @@ export function PrototypeChangeLogPanel({
     storageReady,
     storageConfigured,
   } = useCommentStore();
-  const { overview, ready: metaReady, error: metaError, setOverview } =
-    useChangelogMeta();
-  const [draftOverview, setDraftOverview] = useState(overview);
+  const review = usePrototypeReview();
+  const { value: description, updateValue: updateDescription } =
+    usePersistedLocalString(
+      prototypeReviewPreferenceKey(review.slug, "changelog-description-brief"),
+      "",
+    );
+  const {
+    copy: copyDescriptionPrompt,
+    icon: copyDescriptionIcon,
+    isCopied: isDescriptionCopied,
+  } = useCopyToClipboard();
   const changelogAnnotations = useMemo(
     () => filterAnnotationsByChannel(annotations, "changelog"),
     [annotations],
   );
+  const canCopyDescription = description.trim().length > 0;
 
-  useEffect(() => {
-    if (metaReady) {
-      setDraftOverview(overview);
-    }
-  }, [metaReady, overview]);
-
-  const isOverviewDirty = draftOverview !== overview;
+  const handleCopyDescriptionPrompt = () => {
+    if (!canCopyDescription) return;
 
-  const handleOverviewChange = useCallback(
-    (event: ChangeEvent<HTMLTextAreaElement>) => {
-      setDraftOverview(event.target.value);
-    },
-    [],
-  );
+    const origin =
+      typeof window !== "undefined" ? window.location.origin : undefined;
 
-  const handleSaveOverview = useCallback(() => {
-    setOverview(draftOverview);
-  }, [draftOverview, setOverview]);
+    copyDescriptionPrompt(
+      buildChangelogDescriptionCopyText({
+        slug: review.slug,
+        description,
+        origin,
+      }),
+    );
+  };
 
   return (
     <div className="flex flex-col">
       <section className={CHANGELOG_SECTION_CLASS}>
-        <div className="flex items-center justify-between gap-2">
-          <span className={CHANGELOG_SECTION_TITLE_CLASS}>Description</span>
-          {metaReady && !metaError ? (
-            <ToolbarIconButton
-              onClick={handleSaveOverview}
-              disabled={!isOverviewDirty}
-              aria-label="Save description"
-            >
-              <Save size={16} strokeWidth={2} aria-hidden />
-            </ToolbarIconButton>
-          ) : null}
-        </div>
-        {!metaReady ? (
-          <p className="text-muted-foreground text-xs">Loading description…</p>
-        ) : metaError ? (
-          <p className="text-destructive text-xs">{metaError}</p>
-        ) : (
-          <textarea
-            id="prototype-changelog-overview"
-            value={draftOverview}
-            onChange={handleOverviewChange}
-            rows={1}
-            placeholder="Summarize what changed and why…"
-            aria-label="Description"
-            className={CHANGELOG_OVERVIEW_FIELD_CLASS}
-          />
-        )}
+        <span className={CHANGELOG_SECTION_TITLE_CLASS}>Description</span>
+        <textarea
+          id="prototype-changelog-overview"
+          value={description}
+          onChange={(event) => updateDescription(event.target.value)}
+          rows={3}
+          placeholder="Summarize what changed and why…"
+          aria-label="Description"
+          className={CHANGELOG_OVERVIEW_FIELD_CLASS}
+        />
+        <Button
+          type="button"
+          variant="chrome"
+          size="sm"
+          className="h-8 gap-1.5 self-start"
+          disabled={!canCopyDescription}
+          onClick={handleCopyDescriptionPrompt}
+          aria-label="Copy description prompt"
+        >
+          {isDescriptionCopied ? "Copied prompt" : "Copy prompt"}
+          {copyDescriptionIcon}
+        </Button>
       </section>
 
       <PrototypeReferenceDocs

package/src/components/prototypes/prototype-comment-provider.tsx

@@ -4,7 +4,6 @@ import type { ReactNode } from "react";
 
 import { PrototypeTargetIdProvider } from "@prototype/components/prototypes/prototype-target";
 import { CommentProvider } from "@prototype/lib/prototype-comments/react/CommentProvider";
-import { ChangelogMetaProvider } from "@prototype/lib/prototypes/changelog-meta-context";
 import type { PrototypeComponentRegistry } from "@prototype/lib/prototypes/prototype-component-registry";
 import { getPrototypeComponentRegistryForSlug } from "@prototype/lib/prototypes/create-prototype-registry";
 import {

package/src/components/prototypes/prototype-review-chrome.tsx

@@ -48,6 +48,7 @@ import {
   LayoutGrid,
   MapPin,
   MessageSquare,
+  MessageSquarePlus,
   Monitor,
   Moon,
   Network,
@@ -250,6 +251,7 @@ function ReviewToolbarButton({
   onClick,
   hoverOnly = false,
   hoverTriggerProps,
+  commentModeToggle = false,
   children,
 }: {
   label: string;
@@ -260,6 +262,7 @@ function ReviewToolbarButton({
   onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
   hoverOnly?: boolean;
   hoverTriggerProps?: ToolbarTooltipAnchorProps;
+  commentModeToggle?: boolean;
   children: ReactNode;
 }) {
   return (
@@ -272,6 +275,9 @@ function ReviewToolbarButton({
             pressed && !highlightActive && styles.toolbarButtonHovered,
           )}
           data-active={highlightActive && pressed ? "true" : undefined}
+          data-prototype-comment-mode-toggle={
+            commentModeToggle ? true : undefined
+          }
           aria-label={label}
           aria-pressed={pressed}
           onClick={(event) => {
@@ -1121,6 +1127,21 @@ export function PrototypeReviewChrome({
             </DropdownMenuContent>
           </DropdownMenu>
 
+          {onToggleCommentMode ? (
+            <ReviewToolbarButton
+              label={
+                isCommentModeActive ? "Exit comment mode" : "Add comment"
+              }
+              tooltip="Add comment"
+              pressed={isCommentModeActive ?? false}
+              highlightActive={isCommentModeActive ?? false}
+              commentModeToggle
+              onClick={() => onToggleCommentMode()}
+            >
+              <MessageSquarePlus size={16} strokeWidth={2} />
+            </ReviewToolbarButton>
+          ) : null}
+
           <ReviewToolbarButton
             label={
               review.open && review.sidebarPanel === "comments"
@@ -1204,8 +1225,6 @@ export function PrototypeReviewChrome({
               onSelect={onSelect}
               selectedId={selectedId}
               onClose={onClose}
-              isCommentModeActive={isCommentModeActive}
-              onToggleCommentMode={onToggleCommentMode}
             />,
             sidebarPortalTarget,
           )

package/src/components/prototypes/prototype-review-sidebar.tsx

@@ -7,7 +7,6 @@ import { useCommentStore } from "@prototype/lib/prototype-comments/react/Comment
 import { CommentHeaderCount } from "@prototype/lib/prototype-comments/ui/CommentHeaderCount";
 import { CommentsGrid } from "@prototype/lib/prototype-comments/ui/CommentsGrid";
 import { usePrototypeReview } from "@prototype/lib/prototypes/prototype-review-context";
-import { CommentModeToggleButton } from "@prototype/lib/prototype-comments/ui/CommentModeToggleButton";
 import { Sidebar } from "@prototype/components/platform-ui/sidebar";
 import { EmptyState } from "@prototype/components/platform-ui/empty-state";
 import { PrototypeChangeLogPanel } from "@prototype/components/prototypes/prototype-change-log-panel";
@@ -20,16 +19,12 @@ type PrototypeReviewSidebarProps = {
   onSelect: (id: string) => void;
   selectedId?: string | null;
   onClose: () => void;
-  isCommentModeActive?: boolean;
-  onToggleCommentMode?: () => void;
 };
 
 export function PrototypeReviewSidebar({
   onSelect,
   selectedId,
   onClose,
-  isCommentModeActive = false,
-  onToggleCommentMode,
 }: PrototypeReviewSidebarProps) {
   const review = usePrototypeReview();
   const { annotations, deleteAnnotation, updateAnnotation, resolveAnnotation, storageError, storageReady, storageConfigured } = useCommentStore();
@@ -91,14 +86,6 @@ export function PrototypeReviewSidebar({
           />
         ) : undefined
       }
-      headerActions={
-        isCommentsPanel && onToggleCommentMode ? (
-          <CommentModeToggleButton
-            isActive={isCommentModeActive}
-            onClick={onToggleCommentMode}
-          />
-        ) : undefined
-      }
       onClose={
         isVariantsPanel
           ? review.closeVariants

package/src/components/shell/prototype-gallery-nav.tsx

@@ -5,7 +5,7 @@ import { Button } from "@prototype/components/ui/button";
 import { PrototypeLinkSourceModal } from "@prototype/components/shell/prototype-link-source-modal";
 import { cn } from "@prototype/lib/utils";
 import { usePrototypeToolTheme } from "@prototype/lib/prototypes/use-prototype-tool-theme";
-import { Moon, Pencil, Shapes, Sun, LayoutDashboard } from "lucide-react";
+import { LibraryBig, Moon, Pencil, Shapes, Sun } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { useState } from "react";
@@ -19,7 +19,7 @@ const GALLERY_NAV_ITEMS = [
   {
     href: "/component-library",
     label: "Component Library",
-    icon: LayoutDashboard,
+    icon: LibraryBig,
   },
 ] as const;
 
@@ -37,7 +37,7 @@ export function PrototypeGalleryNav({
   const [linkSourceOpen, setLinkSourceOpen] = useState(false);
 
   return (
-    <aside className="border-[var(--tool-chrome-border)] bg-[var(--bg-ground)] flex h-full min-h-0 w-56 shrink-0 flex-col self-stretch overflow-hidden border-r">
+    <aside className="border-[var(--tool-chrome-border)] bg-[var(--bg-main)] flex h-full min-h-0 w-56 shrink-0 flex-col self-stretch overflow-hidden border-r">
       <nav aria-label="Gallery" className="flex flex-col gap-1 p-3">
         {GALLERY_NAV_ITEMS.map(({ href, label, icon: Icon }) => {
           const isActive =

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

@@ -21,7 +21,7 @@ export function PrototypeGalleryShell({
   return (
     <PrototypeProvider className="bg-[var(--bg-main)] flex h-full min-h-0 w-full flex-1 flex-col overflow-hidden">
       {footer ? (
-        <div className="border-[var(--tool-chrome-border)] bg-[var(--bg-ground)] flex shrink-0 items-center justify-end border-b px-10 py-3 lg:px-16">
+        <div className="border-[var(--tool-chrome-border)] bg-[var(--bg-main)] flex shrink-0 items-center justify-end border-b px-10 py-3 lg:px-16">
           {footer}
         </div>
       ) : null}
@@ -31,7 +31,7 @@ export function PrototypeGalleryShell({
           sourceDirectoryName={sourceDirectoryName}
           sourcePath={sourcePath}
         />
-        <main className="bg-[var(--bg-main)] flex min-h-0 flex-1 flex-col overflow-hidden">
+        <main className="bg-[var(--bg-ground)] flex min-h-0 flex-1 flex-col overflow-hidden">
           {children}
         </main>
       </div>
@@ -52,7 +52,7 @@ export function PrototypeGalleryPageLayout({
   return (
     <div className="flex h-full min-h-0 flex-1 flex-col overflow-hidden">
       {header}
-      <div className="bg-[var(--bg-main)] min-h-0 flex-1 overflow-y-auto overscroll-y-contain">
+      <div className="bg-[var(--bg-ground)] min-h-0 flex-1 overflow-y-auto overscroll-y-contain">
         <div className="h-fit w-full">{children}</div>
       </div>
     </div>
@@ -75,7 +75,7 @@ export function PrototypeGalleryHeader({
   return (
     <div
       className={cn(
-        "border-[var(--tool-chrome-border)] bg-[var(--bg-ground)] shrink-0 border-b px-10 py-6 lg:px-16",
+        "border-[var(--tool-chrome-border)] bg-[var(--bg-main)] shrink-0 border-b px-10 py-6 lg:px-16",
         className,
       )}
     >

package/src/components/shell/prototype-plugin-update-popup.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { Button } from "@prototype/components/ui/button";
+import { buildUpgradeProtoPluginCopyText } from "@prototype/lib/prototypes/upgrade-proto-plugin-prompt";
+import { useProtoPluginVersionCheck } from "@prototype/lib/prototypes/use-proto-plugin-version-check";
+import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
+import { cn } from "@prototype/lib/utils";
+import { X } from "lucide-react";
+import { toast } from "sonner";
+
+export function PrototypePluginUpdatePopup() {
+  const { status, shouldShowPopup, dismiss } = useProtoPluginVersionCheck();
+  const { copy, icon, isCopied } = useCopyToClipboard();
+
+  if (!shouldShowPopup || !status?.installed || !status.latest) {
+    return null;
+  }
+
+  const handleCopy = async () => {
+    try {
+      await copy(
+        buildUpgradeProtoPluginCopyText({
+          installed: status.installed!,
+          latest: status.latest!,
+        }),
+      );
+    } catch {
+      toast.error("Copy error", {
+        description: "Failed to copy upgrade prompt",
+      });
+    }
+  };
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cn(
+        "border-border bg-card ring-border pointer-events-auto fixed bottom-4 left-4 z-[1050] flex w-[min(20rem,calc(100vw-2rem))] flex-col gap-3 rounded-xl border p-4 shadow-lg ring-[0.5px]",
+      )}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-medium text-foreground">Update proto-plugin</p>
+          <p className="mt-1 text-sm text-muted-foreground">
+            v{status.latest} is available. You&apos;re on v{status.installed}.
+          </p>
+        </div>
+        <button
+          type="button"
+          aria-label="Dismiss update notification"
+          className="text-muted-foreground hover:text-foreground shrink-0 rounded p-1 transition-colors duration-200 ease"
+          onClick={dismiss}
+        >
+          <X size={14} />
+        </button>
+      </div>
+
+      <Button
+        type="button"
+        variant="outline"
+        size="sm"
+        className="h-8 w-fit cursor-pointer gap-1.5"
+        onClick={() => {
+          void handleCopy();
+        }}
+        aria-label="Copy upgrade prompt"
+      >
+        {isCopied ? "Copied prompt" : "Copy prompt"}
+        {icon}
+      </Button>
+    </div>
+  );
+}

package/src/components/ui/button.tsx

@@ -4,7 +4,7 @@ import { Slot } from "@radix-ui/react-slot";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const buttonVariants = cva(
   "inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",

package/src/components/ui/dialog.tsx

@@ -4,12 +4,12 @@ import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "lucide-react";
 import * as React from "react";
 
-import { isCommentCaptureBlockedTarget } from "@prototype/lib/prototype-comments/core/comment-capture-blocked";
+import { isCommentCaptureBlockedTarget } from "../../lib/prototype-comments/core/comment-capture-blocked";
 import {
   getPrototypeDialogPortalContainer,
   getPrototypeToolDialogPortalContainer,
-} from "@prototype/lib/tool-portal";
-import { cn } from "@prototype/lib/utils";
+} from "../../lib/tool-portal";
+import { cn } from "../../lib/utils";
 
 import styles from "./dialog.module.scss";
 

package/src/components/ui/dropdown-menu.tsx

@@ -4,8 +4,8 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
 import { Check, ChevronRight, Circle } from "lucide-react";
 import * as React from "react";
 
-import { getPrototypePortalContainer } from "@prototype/lib/tool-portal";
-import { cn } from "@prototype/lib/utils";
+import { getPrototypePortalContainer } from "../../lib/tool-portal";
+import { cn } from "../../lib/utils";
 
 const DropdownMenu = DropdownMenuPrimitive.Root;
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;

package/src/components/ui/input.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<"input">>(
   ({ className, type, ...props }, ref) => {

package/src/components/ui/label.tsx

@@ -4,7 +4,7 @@ import * as LabelPrimitive from "@radix-ui/react-label";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const labelVariants = cva(
   "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",

package/src/components/ui/option-select.tsx

@@ -3,14 +3,14 @@
 import { ChevronDown } from "lucide-react";
 import type { ReactNode } from "react";
 
-import { Button } from "@prototype/components/ui/button";
+import { Button } from "./button";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuTrigger,
-} from "@prototype/components/ui/dropdown-menu";
-import { cn } from "@prototype/lib/utils";
+} from "./dropdown-menu";
+import { cn } from "../../lib/utils";
 
 export type OptionSelectItem<T extends string = string> = {
   value: T;

package/src/components/ui/scroll-area.tsx

@@ -3,7 +3,7 @@
 import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const ScrollArea = React.forwardRef<
   React.ComponentRef<typeof ScrollAreaPrimitive.Root>,

package/src/components/ui/separator.tsx

@@ -3,7 +3,7 @@
 import * as SeparatorPrimitive from "@radix-ui/react-separator";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const Separator = React.forwardRef<
   React.ComponentRef<typeof SeparatorPrimitive.Root>,

package/src/components/ui/slider.tsx

@@ -3,7 +3,7 @@
 import * as SliderPrimitive from "@radix-ui/react-slider";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const Slider = React.forwardRef<
   React.ComponentRef<typeof SliderPrimitive.Root>,

package/src/components/ui/switch.tsx

@@ -3,7 +3,7 @@
 import * as SwitchPrimitives from "@radix-ui/react-switch";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const Switch = React.forwardRef<
   React.ComponentRef<typeof SwitchPrimitives.Root>,

package/src/components/ui/tabs.tsx

@@ -3,7 +3,7 @@
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const Tabs = TabsPrimitive.Root;
 

package/src/components/ui/toggle-group.tsx

@@ -4,7 +4,7 @@ import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { type VariantProps, cva } from "class-variance-authority";
 import * as React from "react";
 
-import { cn } from "@prototype/lib/utils";
+import { cn } from "../../lib/utils";
 
 const toggleVariants = cva(
   "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground",

package/src/components/ui/tooltip.tsx

@@ -3,8 +3,8 @@
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 import * as React from "react";
 
-import { getPrototypePortalContainer } from "@prototype/lib/tool-portal";
-import { cn } from "@prototype/lib/utils";
+import { getPrototypePortalContainer } from "../../lib/tool-portal";
+import { cn } from "../../lib/utils";
 
 const TooltipProvider = TooltipPrimitive.Provider;
 

package/src/config/prototype-site-layout-client.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { PrototypePluginUpdatePopup } from "@prototype/components/shell/prototype-plugin-update-popup";
 import { usePathname } from "next/navigation";
 import type { ComponentType, ReactNode } from "react";
 
@@ -35,6 +36,7 @@ export function PrototypeSiteLayoutClient({
         >
           {children}
         </GalleryShell>
+        <PrototypePluginUpdatePopup />
         {toaster}
       </div>
     );
@@ -43,6 +45,7 @@ export function PrototypeSiteLayoutClient({
   return (
     <div className="bg-[var(--bg-ground)] flex h-svh overflow-hidden">
       {children}
+      <PrototypePluginUpdatePopup />
       {toaster}
     </div>
   );

package/src/config/with-prototype.ts

@@ -1,3 +1,6 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
 import type { NextConfig } from "next";
 
 export type WithPrototypeOptions = {
@@ -5,10 +8,25 @@ export type WithPrototypeOptions = {
   nextConfig?: NextConfig;
 };
 
+/** Package root — resolved lazily so this module is safe if ever pulled into a bundle. */
+function getPackageRoot(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+
+function getPrototypeInternalAlias() {
+  return {
+    "@prototype": path.join(getPackageRoot(), "src"),
+  } as const;
+}
+
 export function withPrototype(
   options: WithPrototypeOptions = {},
 ): NextConfig {
   const { nextConfig = {} } = options;
+  const prototypeInternalAlias = getPrototypeInternalAlias();
+
+  const existingTurbopack = nextConfig.turbopack ?? {};
+  const existingResolveAlias = existingTurbopack.resolveAlias ?? {};
 
   return {
     ...nextConfig,
@@ -28,6 +46,21 @@ export function withPrototype(
       ...(nextConfig.transpilePackages ?? []),
       "proto-plugin",
     ],
+    turbopack: {
+      ...existingTurbopack,
+      resolveAlias: {
+        ...existingResolveAlias,
+        ...prototypeInternalAlias,
+      },
+    },
+    webpack: (config, ctx) => {
+      config.resolve ??= {};
+      config.resolve.alias = {
+        ...config.resolve.alias,
+        ...prototypeInternalAlias,
+      };
+      return nextConfig.webpack?.(config, ctx) ?? config;
+    },
     images: {
       ...nextConfig.images,
       localPatterns: [

package/src/index.ts

@@ -1,10 +1,14 @@
 export { definePrototypeConfig } from "./config/define-prototype-config";
-export { createPrototypeGalleryPage } from "./config/create-prototype-gallery-page";
+// NOTE: `createPrototypeGalleryPage` is server-only (reads the screenshot manifest
+// from disk) and lives in `proto-plugin/server`. Keeping it out of this barrel is
+// what lets client prototype components import from `proto-plugin` safely.
 export { createPrototypeComponentLibraryPage } from "./config/create-prototype-component-library-page";
 export { createPrototypePage } from "./config/create-prototype-page";
 export { createPrototypeStateMapPage } from "./config/create-prototype-state-map-page";
 export { createPrototypeSiteLayout } from "./config/create-prototype-site-layout";
-export { withPrototype } from "./config/with-prototype";
+// NOTE: `withPrototype` uses Node path APIs and belongs in `proto-plugin/with-prototype`
+// (next.config.ts only). Do not re-export it here — the barrel is imported by client
+// prototype components and must stay browser-safe.
 
 export {
   createPrototypeRegistry,
@@ -55,6 +59,16 @@ export {
 
 export { usePrototypeComments } from "./lib/prototypes/use-prototype-comments";
 
+export {
+  SHARE_TARGET_PARAM,
+  SHARE_STATE_PARAM,
+  SHARE_COMMENT_PARAM,
+  encodeShareState,
+  decodeShareState,
+  readShareLinkParams,
+} from "./lib/prototypes/prototype-share-link";
+export type { ShareLinkParams } from "./lib/prototypes/prototype-share-link";
+
 export {
   usePersistPrototypeLiveState,
   readPersistedPrototypeLiveState,
@@ -63,6 +77,8 @@ export {
 export type {
   DesignExplorationBaselineOption,
   DesignExplorationConfig,
+  DesignExplorationRationale,
+  MobbinReference,
 } from "./lib/prototypes/design-exploration-types";
 
 export {

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

package/src/lib/prototypes/proto-plugin-version.ts

@@ -0,0 +1,19 @@
+export type ProtoPluginVersionStatus = {
+  installed: string | null;
+  latest: string | null;
+  updateAvailable: boolean;
+  isWorkspaceLink: boolean;
+  repositoryUrl?: string;
+};
+
+export const PROTOTYPE_PLUGIN_VERSION_PATH = "/api/proto-plugin/version";
+
+export async function fetchProtoPluginVersionStatus(): Promise<ProtoPluginVersionStatus> {
+  const response = await fetch(PROTOTYPE_PLUGIN_VERSION_PATH);
+
+  if (!response.ok) {
+    throw new Error("Failed to check proto-plugin version.");
+  }
+
+  return (await response.json()) as ProtoPluginVersionStatus;
+}

package/src/lib/prototypes/upgrade-proto-plugin-prompt.ts

@@ -0,0 +1,40 @@
+export type UpgradeProtoPluginPromptOptions = {
+  installed: string;
+  latest: string;
+};
+
+export function buildUpgradeProtoPluginPrompt({
+  installed,
+  latest,
+}: UpgradeProtoPluginPromptOptions): string {
+  return [
+    `Upgrade \`proto-plugin\` in this host app from \`${installed}\` to \`${latest}\`. **Do every step yourself** — the user should not run commands manually.`,
+    "",
+    "## Your job",
+    `Update the dependency, restart the dev server if needed, and confirm the gallery and at least one prototype still work on \`${latest}\`.`,
+    "",
+    "## Versions",
+    `- Installed: \`${installed}\``,
+    `- Latest: \`${latest}\``,
+    "",
+    "## Steps",
+    "1. Detect the package manager from the lockfile (`pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`).",
+    "2. Update the dependency:",
+    `   - pnpm: \`pnpm update proto-plugin\` or \`pnpm add proto-plugin@${latest}\``,
+    `   - npm: \`npm install proto-plugin@${latest}\``,
+    `   - yarn: \`yarn add proto-plugin@${latest}\``,
+    "3. Restart the dev server if it is already running.",
+    `4. Skim \`node_modules/proto-plugin/AGENTS.md\` (or the package changelog on npm) for breaking changes since \`${installed}\`.`,
+    "5. Open `/` and one prototype preview — confirm the gallery and review chrome load without errors.",
+    "",
+    "## Notes",
+    "- Do not modify prototype source under `src/prototypes/` unless AGENTS.md or the changelog requires migration steps for this upgrade.",
+    "- If the update fails (peer dependency conflicts, build errors), diagnose and fix before stopping.",
+  ].join("\n");
+}
+
+export function buildUpgradeProtoPluginCopyText(
+  options: UpgradeProtoPluginPromptOptions,
+): string {
+  return buildUpgradeProtoPluginPrompt(options);
+}

package/src/lib/prototypes/use-proto-plugin-version-check.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import {
+  fetchProtoPluginVersionStatus,
+  type ProtoPluginVersionStatus,
+} from "@prototype/lib/prototypes/proto-plugin-version";
+import { usePersistedLocalString } from "@prototype/lib/prototypes/use-persisted-local-state";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+const DISMISSED_VERSION_KEY = "prototype-review:global:dismissed-plugin-version";
+
+export function useProtoPluginVersionCheck() {
+  const [status, setStatus] = useState<ProtoPluginVersionStatus | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const { value: dismissedVersion, updateValue: setDismissedVersion } =
+    usePersistedLocalString(DISMISSED_VERSION_KEY, "");
+
+  useEffect(() => {
+    let cancelled = false;
+
+    void (async () => {
+      try {
+        const nextStatus = await fetchProtoPluginVersionStatus();
+        if (!cancelled) {
+          setStatus(nextStatus);
+        }
+      } catch {
+        if (!cancelled) {
+          setStatus(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const dismiss = useCallback(() => {
+    if (status?.latest) {
+      setDismissedVersion(status.latest);
+    }
+  }, [setDismissedVersion, status?.latest]);
+
+  const shouldShowPopup = useMemo(() => {
+    if (isLoading || !status?.updateAvailable || !status.latest || !status.installed) {
+      return false;
+    }
+
+    if (!dismissedVersion) {
+      return true;
+    }
+
+    return dismissedVersion !== status.latest;
+  }, [dismissedVersion, isLoading, status]);
+
+  return {
+    status,
+    shouldShowPopup,
+    dismiss,
+    isLoading,
+  };
+}

package/src/server/create-host-api-route.ts

@@ -10,6 +10,7 @@ import {
 } from "./create-prototype-api-routes";
 import { createGalleryApi } from "./gallery/create-gallery-api";
 import { GET as getPrototypeStorageStatus } from "./prototype-storage-status-route";
+import { GET as getProtoPluginVersion } from "./proto-plugin-version-route";
 import { GET as getPrVercelPreview } from "./pr-vercel-preview-route";
 
 type ApiRouteContext = {
@@ -42,6 +43,12 @@ export function createPrototypeApiRoute(_config: PrototypeConfig) {
       }
     }
 
+    if (path[0] === "proto-plugin" && path.length === 2 && path[1] === "version") {
+      if (method === "GET") {
+        return getProtoPluginVersion();
+      }
+    }
+
     if (path[0] === "prototypes" && path.length === 2 && path[1] === "storage-status") {
       if (method === "GET") {
         return getPrototypeStorageStatus();

package/src/server/proto-plugin-version-route.ts

@@ -0,0 +1,145 @@
+import { readFileSync, lstatSync } from "fs";
+import { join } from "path";
+
+import { NextResponse } from "next/server";
+
+const PACKAGE_NAME = "proto-plugin";
+const NPM_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CACHE_TTL_MS = 60 * 60 * 1000;
+
+export type ProtoPluginVersionStatus = {
+  installed: string | null;
+  latest: string | null;
+  updateAvailable: boolean;
+  isWorkspaceLink: boolean;
+  repositoryUrl?: string;
+};
+
+type NpmLatestResponse = {
+  version?: string;
+  repository?: { url?: string };
+};
+
+let cachedLatest: { version: string; repositoryUrl?: string; fetchedAt: number } | null =
+  null;
+
+function parseSemver(version: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function isNewerVersion(latest: string, installed: string): boolean {
+  const latestParts = parseSemver(latest);
+  const installedParts = parseSemver(installed);
+  if (!latestParts || !installedParts) return false;
+
+  for (let index = 0; index < 3; index += 1) {
+    if (latestParts[index]! > installedParts[index]!) return true;
+    if (latestParts[index]! < installedParts[index]!) return false;
+  }
+
+  return false;
+}
+
+function readInstalledVersion(cwd: string): {
+  installed: string | null;
+  isWorkspaceLink: boolean;
+} {
+  const packagePath = join(cwd, "node_modules", PACKAGE_NAME, "package.json");
+  const linkPath = join(cwd, "node_modules", PACKAGE_NAME);
+
+  let isWorkspaceLink = false;
+
+  try {
+    isWorkspaceLink = lstatSync(linkPath).isSymbolicLink();
+  } catch {
+    try {
+      const hostPkg = JSON.parse(
+        readFileSync(join(cwd, "package.json"), "utf8"),
+      ) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      const depSpec =
+        hostPkg.dependencies?.[PACKAGE_NAME] ??
+        hostPkg.devDependencies?.[PACKAGE_NAME];
+      isWorkspaceLink = depSpec?.startsWith("workspace:") ?? false;
+    } catch {
+      // Ignore — treat as non-workspace.
+    }
+  }
+
+  try {
+    const pkg = JSON.parse(readFileSync(packagePath, "utf8")) as { version?: string };
+    return { installed: pkg.version ?? null, isWorkspaceLink };
+  } catch {
+    return { installed: null, isWorkspaceLink };
+  }
+}
+
+async function fetchLatestFromNpm(): Promise<{
+  version: string | null;
+  repositoryUrl?: string;
+}> {
+  const now = Date.now();
+
+  if (cachedLatest && now - cachedLatest.fetchedAt < CACHE_TTL_MS) {
+    return {
+      version: cachedLatest.version,
+      repositoryUrl: cachedLatest.repositoryUrl,
+    };
+  }
+
+  try {
+    const response = await fetch(NPM_LATEST_URL, {
+      next: { revalidate: 3600 },
+    });
+
+    if (!response.ok) {
+      return { version: null };
+    }
+
+    const data = (await response.json()) as NpmLatestResponse;
+    const version = data.version ?? null;
+    const repositoryUrl = data.repository?.url?.replace(/^git\+/, "").replace(/\.git$/, "");
+
+    if (version) {
+      cachedLatest = { version, repositoryUrl, fetchedAt: now };
+    }
+
+    return { version, repositoryUrl };
+  } catch {
+    return { version: null };
+  }
+}
+
+export async function GET() {
+  const cwd = process.cwd();
+  const { installed, isWorkspaceLink } = readInstalledVersion(cwd);
+
+  if (isWorkspaceLink) {
+    const status: ProtoPluginVersionStatus = {
+      installed,
+      latest: null,
+      updateAvailable: false,
+      isWorkspaceLink: true,
+    };
+    return NextResponse.json(status);
+  }
+
+  const { version: latest, repositoryUrl } = await fetchLatestFromNpm();
+
+  const updateAvailable =
+    installed != null && latest != null && isNewerVersion(latest, installed);
+
+  const status: ProtoPluginVersionStatus = {
+    installed,
+    latest,
+    updateAvailable,
+    isWorkspaceLink: false,
+    repositoryUrl,
+  };
+
+  return NextResponse.json(status);
+}

package/src/server.ts

@@ -1,5 +1,7 @@
 import "server-only";
 
+export { createPrototypeGalleryPage } from "./config/create-prototype-gallery-page";
+
 export {
   readScreenshotManifest,
   touchScreenshotManifest,

package/src/styles/globals.css

@@ -40,17 +40,17 @@
      Chrome (ground) is darkest for sidebar + header; content (bg) is a lighter
      elevated panel for the gallery grid and review preview frame.
 
-     Neutral scale (measured against the #1a1a1a content surface):
+     Neutral scale (measured against the #151515 content surface):
        heading  #f0f0f0  ~13:1   crisp titles
        text     #d0d0d0  ~9:1    body copy
        muted    #a0a0a0  ~5:1    labels, descriptions (AA)
        icon     #9a9a9a          glyphs, dimmer than body
        border   #333333          hairline dividers
        strong   #454545          inputs, structural edges */
-  --tool-chrome-ground: #0f0f0f;
-  --tool-chrome-bg: #1a1a1a;
-  --tool-chrome-surface: #202020;
-  --tool-chrome-surface-muted: #161616;
+  --tool-chrome-ground: #121212;
+  --tool-chrome-bg: #151515;
+  --tool-chrome-surface: #1c1c1c;
+  --tool-chrome-surface-muted: #181818;
   --tool-chrome-text: #d0d0d0;
   --tool-chrome-text-heading: #f0f0f0;
   --tool-chrome-text-muted: #9c9c9c;
@@ -83,7 +83,7 @@
   --bg-main: var(--tool-chrome-bg);
   --bg-top: var(--tool-chrome-surface);
   --bg-subtle: var(--tool-chrome-surface-muted);
-  --bg-layered: #202020;
+  --bg-layered: #1c1c1c;
   --bg-invert: var(--tool-chrome-text-heading);
   --bg-white: var(--tool-chrome-bg);
 
@@ -165,7 +165,7 @@
   --color-bg-main: var(--tool-chrome-bg);
   --color-bg-top: var(--tool-chrome-surface);
   --color-bg-subtle: var(--tool-chrome-surface-muted);
-  --color-bg-layered: #202020;
+  --color-bg-layered: #1c1c1c;
   --color-bg-invert: var(--tool-chrome-text-heading);
   --color-bg-white: var(--tool-chrome-bg);
   --color-text-primary: var(--tool-chrome-text);
@@ -209,7 +209,7 @@
   --bg-main: var(--tool-chrome-bg);
   --bg-top: var(--tool-chrome-bg);
   --bg-subtle: var(--tool-chrome-surface-muted);
-  --bg-layered: #242424;
+  --bg-layered: #1a1a1a;
   --border-faint: var(--tool-chrome-border);
   --border-solid: var(--tool-chrome-border);
   --border-medium: var(--tool-chrome-border-strong);
@@ -241,7 +241,7 @@
   --color-bg-main: var(--tool-chrome-bg);
   --color-bg-top: var(--tool-chrome-bg);
   --color-bg-subtle: var(--tool-chrome-surface-muted);
-  --color-bg-layered: #242424;
+  --color-bg-layered: #1a1a1a;
   --color-text-primary: var(--tool-chrome-text-heading);
   --color-text-secondary: var(--tool-chrome-text);
   --color-text-tertiary: var(--tool-chrome-text-muted);
@@ -490,7 +490,7 @@ html.prototype-theme-transition-disable :is(*, *::before, *::after) {
 
 @media (hover: hover) and (pointer: fine) {
   [data-prototype-root] .tool-toolbar-button:hover {
-    background: #202020;
+    background: var(--tool-chrome-surface);
     color: var(--tool-chrome-icon-hover);
   }
 }
@@ -728,7 +728,7 @@ html.prototype-theme-transition-disable :is(*, *::before, *::after) {
 
 /* State map chrome — dedicated canvas bed + node footer tokens per theme. */
 [data-prototype-root] [data-prototype-state-canvas] {
-  --prototype-state-map-canvas-bg: var(--tool-chrome-bg);
+  --prototype-state-map-canvas-bg: var(--tool-chrome-ground);
   --prototype-state-map-node-surface: var(--tool-chrome-surface);
   --prototype-state-map-node-preview-bg: var(--tool-chrome-surface-muted);
   --prototype-state-map-node-footer-bg: var(--tool-chrome-surface-muted);
@@ -740,12 +740,12 @@ html.prototype-theme-transition-disable :is(*, *::before, *::after) {
 }
 
 [data-prototype-root][data-prototype-comment-theme="dark"] [data-prototype-state-canvas] {
-  --prototype-state-map-canvas-bg: #282828;
-  --prototype-state-map-node-surface: #343434;
-  --prototype-state-map-node-preview-bg: #303030;
-  --prototype-state-map-node-footer-bg: #404040;
-  --prototype-state-map-node-footer-border: #525252;
-  --prototype-state-map-node-footer-text: #ffffff;
+  --prototype-state-map-canvas-bg: var(--tool-chrome-ground);
+  --prototype-state-map-node-surface: var(--tool-chrome-surface);
+  --prototype-state-map-node-preview-bg: var(--tool-chrome-surface-muted);
+  --prototype-state-map-node-footer-bg: var(--tool-chrome-surface-muted);
+  --prototype-state-map-node-footer-border: var(--tool-chrome-border-strong);
+  --prototype-state-map-node-footer-text: var(--tool-chrome-text-heading);
 }
 
 /* Restore host prototype preview theme inside screenshot capture and source