proto-plugin 0.1.0 → 0.1.2

package/src/components/prototypes/prototype-variant-explorer.tsx

@@ -4,19 +4,16 @@ import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
 import { PrototypeControlGroup } from "@prototype/components/prototypes/prototype-control";
 import { PrototypeDesignBriefModal } from "@prototype/components/prototypes/prototype-design-brief-modal";
 import { PrototypeDesignBriefPanel } from "@prototype/components/prototypes/prototype-design-brief-panel";
-import {
-  PrototypeComponent,
-  usePrototypeSlug,
-} from "@prototype/components/prototypes/prototype-target";
+import { PrototypeComponent } from "@prototype/components/prototypes/prototype-target";
 import { PrototypeVariantTabs } from "@prototype/components/prototypes/prototype-variant-tabs";
 import {
   buildBriefOverviewCopyText,
+  getDesignExplorationDisplayOptions,
   type DesignExplorationConfig,
 } from "@prototype/lib/prototypes/design-exploration-types";
 import { usePrototypeReviewOptional } from "@prototype/lib/prototypes/prototype-review-context";
-import { useDesignExplorationDefault } from "@prototype/lib/prototypes/use-design-exploration-default";
 import { usePersistedLocalString } from "@prototype/lib/prototypes/use-persisted-local-state";
-import { ChevronDown, ChevronUp, LayoutGrid } from "lucide-react";
+import { LayoutGrid } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 
 const OVERVIEW_CONTROL_BUTTON_CLASS = "tool-toolbar-button";
@@ -35,6 +32,12 @@ type PrototypeVariantExplorerProps<TVariant extends string> =
      * design explorations available in the review sidebar.
      */
     registerOnly?: boolean;
+    /**
+     * When true, skips rendering the active variant inline on the page while
+     * still using `renderers` in the design-brief sidebar/modal. Use when the
+     * live page already reflects the selected variant (e.g. a full-page canvas).
+     */
+    hideInlinePreview?: boolean;
     /** When set, registers this exploration in the review sidebar. */
     variantSet?: {
       id: string;
@@ -49,34 +52,26 @@ export function PrototypeVariantExplorer<TVariant extends string>({
   variant,
   onVariantChange,
   options,
-  rationale,
   renderers,
+  baseline,
   brief,
   context,
   mobbin,
   variantsSection,
+  defaultVariant,
   variantTabAriaLabel = "variant",
   mobbinGalleryId = "mobbin-inspiration-gallery",
   wrapRoot = true,
   registerOnly = false,
+  hideInlinePreview = false,
   briefConfigFilePath,
   variantSet,
 }: PrototypeVariantExplorerProps<TVariant>) {
   const review = usePrototypeReviewOptional();
-  const slug = usePrototypeSlug();
-  const validValues = useMemo(
-    () => options.map((option) => option.value),
-    [options],
-  );
-  const {
-    effectiveDefault,
-    setDefaultVariant,
-  } = useDesignExplorationDefault({
-    slug,
-    storageKeyPrefix,
-    validValues,
-  });
-  const [notesExpanded, setNotesExpanded] = useState(false);
+  // Default is stored in the codebase config — not KV. "Make default" copies a
+  // prompt to update `defaultVariant` in the exploration config file.
+  const effectiveDefault = defaultVariant ?? options[0]?.value;
+  const displayOptions = getDesignExplorationDisplayOptions(options, baseline);
   const [overviewOpen, setOverviewOpen] = useState(false);
   const { copy: copyOverview, icon: copyIcon } = useCopyToClipboard();
   const { value: overviewTitle } = usePersistedLocalString(
@@ -88,9 +83,7 @@ export function PrototypeVariantExplorer<TVariant extends string>({
     brief.descriptionDefault,
   );
 
-  const fallbackVariant = options[0]?.value;
-  const activeRationale =
-    rationale[variant] ?? (fallbackVariant ? rationale[fallbackVariant] : undefined);
+  const fallbackVariant = displayOptions[0]?.value;
   const ActiveVariantRenderer =
     renderers[variant] ?? (fallbackVariant ? renderers[fallbackVariant] : null);
   const hideInlineControls = Boolean(review);
@@ -107,11 +100,12 @@ export function PrototypeVariantExplorer<TVariant extends string>({
       variant,
       onVariantChange,
       options,
-      rationale,
       renderers,
+      baseline,
       defaultVariantValue: effectiveDefault,
-      onSetDefaultVariant: setDefaultVariant,
       briefConfigFilePath,
+      explorationLabel: variantSet?.label ?? brief.titleDefault,
+      explorationId: variantSet?.id,
     }),
     [
       brief,
@@ -123,11 +117,12 @@ export function PrototypeVariantExplorer<TVariant extends string>({
       mobbinGalleryId,
       onVariantChange,
       options,
-      rationale,
       renderers,
-      setDefaultVariant,
+      baseline,
       storageKeyPrefix,
       variant,
+      variantSet?.id,
+      variantSet?.label,
       variantsSection,
     ],
   );
@@ -151,8 +146,9 @@ export function PrototypeVariantExplorer<TVariant extends string>({
         overviewTitle,
         overviewDescription,
         options.map((option) => option.value).join(","),
+        baseline.value,
       ].join("|"),
-    [variant, effectiveDefault, overviewTitle, overviewDescription, options],
+    [variant, effectiveDefault, overviewTitle, overviewDescription, options, baseline.value],
   );
 
   const variantSetId = variantSet?.id ?? null;
@@ -205,7 +201,7 @@ export function PrototypeVariantExplorer<TVariant extends string>({
             <div className="flex flex-wrap items-center gap-2">
               <PrototypeVariantTabs
                 idPrefix={variantTabsIdPrefix}
-                options={options}
+                options={displayOptions}
                 value={variant}
                 onValueChange={onVariantChange}
                 keyboardScopeActive={!overviewOpen}
@@ -242,65 +238,21 @@ export function PrototypeVariantExplorer<TVariant extends string>({
                     <LayoutGrid className="size-3.5" />
                   </button>
                 </PrototypeComponent>
-
-                <button
-                  type="button"
-                  className={OVERVIEW_CONTROL_BUTTON_CLASS}
-                  onClick={() => setNotesExpanded((expanded) => !expanded)}
-                  aria-expanded={notesExpanded}
-                  aria-controls={`${componentIdPrefix}-notes`}
-                  aria-label={notesExpanded ? "Hide notes" : "Show notes"}
-                >
-                  {notesExpanded ? (
-                    <ChevronUp className="size-3.5" />
-                  ) : (
-                    <ChevronDown className="size-3.5" />
-                  )}
-                </button>
               </div>
             </div>
-
-            {notesExpanded && activeRationale ? (
-              <PrototypeComponent
-                id={`${componentIdPrefix}.rationale`}
-                className="border-border bg-muted absolute right-0 top-full z-10 mt-2 max-w-md rounded-lg border px-3 py-2.5 text-left"
-              >
-                <div
-                  id={`${componentIdPrefix}-notes`}
-                  className="flex flex-col gap-2"
-                >
-                  <p className="text-sm leading-relaxed">
-                    <span className="text-foreground font-medium">Good</span>
-                    {" · "}
-                    <span className="text-muted-foreground">
-                      {activeRationale.good}
-                    </span>
-                  </p>
-                  <p className="text-sm leading-relaxed">
-                    <span className="text-foreground font-medium">Bad</span>
-                    {" · "}
-                    <span className="text-muted-foreground">
-                      {activeRationale.bad}
-                    </span>
-                  </p>
-                </div>
-              </PrototypeComponent>
-            ) : null}
           </div>
         </PrototypeControlGroup>
       </div>
     ),
     [
-      activeRationale,
       brief.descriptionDefault,
       brief.titleDefault,
       componentIdPrefix,
       copyIcon,
       copyOverview,
       effectiveDefault,
-      notesExpanded,
       onVariantChange,
-      options,
+      displayOptions,
       overviewDescription,
       overviewOpen,
       overviewTitle,
@@ -334,14 +286,16 @@ export function PrototypeVariantExplorer<TVariant extends string>({
           variant={variant}
           onVariantChange={onVariantChange}
           options={options}
-          rationale={rationale}
           renderers={renderers}
+          baseline={baseline}
           defaultVariantValue={effectiveDefault}
-          onSetDefaultVariant={setDefaultVariant}
+          briefConfigFilePath={briefConfigFilePath}
         />
       ) : null}
 
-      {!registerOnly && ActiveVariantRenderer ? ActiveVariantRenderer() : null}
+      {!registerOnly && !hideInlinePreview && ActiveVariantRenderer
+        ? ActiveVariantRenderer()
+        : null}
     </div>
   );
 }

package/src/components/prototypes/prototype-vercel-preview-modal.tsx

@@ -6,11 +6,11 @@ import {
   DialogContent,
   DialogTitle,
 } from "@prototype/components/ui/dialog";
+import { PROTOTYPE_TOOL_MODAL_CLOSE_CLASS } from "@prototype/components/platform-ui/prototype-tool-dialog";
 import { ExternalLink, Loader2, X } from "lucide-react";
 import { useEffect, useState } from "react";
 
-const MODAL_CHROME_BUTTON_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 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";
+const MODAL_CHROME_BUTTON_CLASS = PROTOTYPE_TOOL_MODAL_CLOSE_CLASS;
 
 export type PrototypeVercelPreviewModalProps = {
   open: boolean;
@@ -44,8 +44,9 @@ export function PrototypeVercelPreviewModal({
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent
+        portalScope="tool"
         showCloseButton={false}
-        className="flex h-[min(92svh,calc(100%-2rem))] max-h-[min(92svh,calc(100%-2rem))] w-[min(96rem,calc(100vw-2rem))] max-w-[min(96rem,calc(100vw-2rem))] flex-col gap-0 overflow-hidden p-0 sm:max-w-[min(96rem,calc(100vw-2rem))]"
+        className="tool-dialog-surface flex h-[min(92svh,calc(100%-2rem))] max-h-[min(92svh,calc(100%-2rem))] w-[min(96rem,calc(100vw-2rem))] max-w-[min(96rem,calc(100vw-2rem))] flex-col gap-0 overflow-hidden border-0 p-0 sm:max-w-[min(96rem,calc(100vw-2rem))]"
       >
         <div className="flex items-center justify-between gap-3 border-b border-border px-4 py-3">
           <DialogTitle className="min-w-0 truncate text-sm font-medium">

package/src/components/prototypes/state-map-annotation-tooltip.module.scss

@@ -1,5 +1,5 @@
-$wireframe-bg: #ffffff;
-$wireframe-border: #edebeb;
+$wireframe-bg: var(--tool-chrome-surface);
+$wireframe-border: var(--tool-chrome-border);
 $enter-duration: 0.12s;
 $enter-ease: cubic-bezier(0.215, 0.61, 0.355, 1);
 
@@ -38,7 +38,7 @@ $enter-ease: cubic-bezier(0.215, 0.61, 0.355, 1);
   margin: 0;
   font-size: 0.6875rem;
   line-height: 1.45;
-  color: var(--color-gray-500);
+  color: var(--tool-chrome-text-muted);
   white-space: pre-wrap;
 }
 
@@ -54,13 +54,13 @@ $enter-ease: cubic-bezier(0.215, 0.61, 0.355, 1);
   padding: 0.1875rem 0 0.1875rem 0.875rem;
   font-size: 0.6875rem;
   line-height: 1.45;
-  color: var(--color-gray-500);
+  color: var(--tool-chrome-text-muted);
 
   &::before {
     content: "•";
     position: absolute;
     left: 0;
-    color: var(--color-gray-400);
+    color: var(--tool-chrome-icon);
   }
 
   & + & {
@@ -78,12 +78,12 @@ $enter-ease: cubic-bezier(0.215, 0.61, 0.355, 1);
   @media (hover: hover) and (pointer: fine) {
     &:hover {
       background: color-mix(in srgb, var(--tool-chrome-blue) 6%, $wireframe-bg);
-      color: var(--color-gray-700);
+      color: var(--tool-chrome-text-heading);
     }
   }
 }
 
 .bulletItemActive {
   background: color-mix(in srgb, var(--tool-chrome-blue) 8%, $wireframe-bg);
-  color: var(--color-gray-700);
+  color: var(--tool-chrome-text-heading);
 }

package/src/components/shell/prototype-component-library-empty-state.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { Button } from "@prototype/components/ui/button";
+import { buildPopulateComponentLibraryCopyText } from "@prototype/lib/prototypes/populate-component-library-prompt";
+import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
+
+type PrototypeComponentLibraryEmptyStateProps = {
+  sourcePath?: string;
+  syncConfigPath?: string;
+  componentLibraryPagePath?: string;
+};
+
+export function PrototypeComponentLibraryEmptyState({
+  sourcePath,
+  syncConfigPath,
+  componentLibraryPagePath,
+}: PrototypeComponentLibraryEmptyStateProps) {
+  const { copy, icon, isCopied } = useCopyToClipboard();
+
+  const handleCopy = () => {
+    const origin =
+      typeof window !== "undefined" ? window.location.origin : undefined;
+
+    copy(
+      buildPopulateComponentLibraryCopyText({
+        sourcePath,
+        syncConfigPath,
+        componentLibraryPagePath,
+        origin,
+      }),
+    );
+  };
+
+  return (
+    <div className="max-w-2xl rounded-xl border border-dashed border-[var(--tool-chrome-border)] bg-[var(--tool-chrome-surface-muted)] px-6 py-8 text-[var(--tool-chrome-text-muted)]">
+      <p className="text-sm font-medium text-[var(--tool-chrome-text-heading)]">
+        No components yet
+      </p>
+      <p className="mt-2 text-sm leading-relaxed">
+        Copy the prompt below into your agent. It will inspect the linked source
+        app and port over base styles, UI primitives, and shared building
+        blocks — err on the side of syncing more rather than less.
+      </p>
+      <div className="mt-5 flex items-center gap-3">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="h-8 gap-1.5 border-[var(--tool-chrome-border-strong)] text-[var(--tool-chrome-text-heading)] hover:text-[var(--tool-chrome-text-heading)]"
+          onClick={handleCopy}
+          aria-label="Copy component library population prompt"
+        >
+          {isCopied ? "Copied prompt" : "Copy prompt"}
+          {icon}
+        </Button>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,124 @@
+"use client";
+
+import { IconButton } from "@prototype/components/platform-ui/icon-button";
+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 Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useState } from "react";
+
+const GALLERY_NAV_ITEMS = [
+  {
+    href: "/",
+    label: "Prototypes",
+    icon: Shapes,
+  },
+  {
+    href: "/component-library",
+    label: "Component Library",
+    icon: LayoutDashboard,
+  },
+] as const;
+
+type PrototypeGalleryNavProps = {
+  sourceDirectoryName?: string;
+  sourcePath?: string;
+};
+
+export function PrototypeGalleryNav({
+  sourceDirectoryName,
+  sourcePath,
+}: PrototypeGalleryNavProps) {
+  const pathname = usePathname();
+  const { theme, toggleTheme } = usePrototypeToolTheme();
+  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">
+      <nav aria-label="Gallery" className="flex flex-col gap-1 p-3">
+        {GALLERY_NAV_ITEMS.map(({ href, label, icon: Icon }) => {
+          const isActive =
+            href === "/"
+              ? pathname === "/"
+              : pathname === href || pathname.startsWith(`${href}/`);
+
+          return (
+            <Link
+              key={href}
+              href={href}
+              aria-current={isActive ? "page" : undefined}
+              className={cn(
+                "flex items-center gap-2.5 rounded-md px-3 py-2 text-sm font-medium transition-colors",
+                isActive
+                  ? "bg-[var(--tool-chrome-gray-highlight)] text-[var(--tool-chrome-text-heading)]"
+                  : "text-[var(--tool-chrome-text-muted)] hover:bg-[var(--tool-chrome-gray-highlight)] hover:text-[var(--tool-chrome-text-heading)]",
+              )}
+            >
+              <Icon className="size-4 shrink-0" aria-hidden />
+              {label}
+            </Link>
+          );
+        })}
+      </nav>
+
+      <div className="border-[var(--tool-chrome-border)] mt-auto border-t p-3">
+        <div className="flex min-w-0 items-center gap-2">
+          <IconButton
+            type="button"
+            variant="ghost"
+            size="icon"
+            onClick={toggleTheme}
+            aria-label={
+              theme === "light" ? "Switch to dark mode" : "Switch to light mode"
+            }
+            className="size-8 shrink-0 text-[var(--tool-chrome-text-muted)] hover:text-[var(--tool-chrome-text-heading)]"
+          >
+            {theme === "light" ? (
+              <Moon size={16} strokeWidth={2} aria-hidden />
+            ) : (
+              <Sun size={16} strokeWidth={2} aria-hidden />
+            )}
+          </IconButton>
+          {sourceDirectoryName ? (
+            <>
+              <span
+                className="min-w-0 flex-1 truncate text-xs text-[var(--tool-chrome-text-muted)]"
+                title={sourcePath ?? sourceDirectoryName}
+              >
+                {sourceDirectoryName}
+              </span>
+              <IconButton
+                type="button"
+                variant="ghost"
+                size="icon"
+                onClick={() => setLinkSourceOpen(true)}
+                aria-label="Change linked source app"
+                className="size-7 shrink-0 text-[var(--tool-chrome-text-muted)] hover:text-[var(--tool-chrome-text-heading)]"
+              >
+                <Pencil size={14} strokeWidth={2} aria-hidden />
+              </IconButton>
+            </>
+          ) : (
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => setLinkSourceOpen(true)}
+              className="h-9 min-w-0 flex-1 justify-center rounded-lg text-sm font-medium"
+            >
+              Link source
+            </Button>
+          )}
+        </div>
+      </div>
+
+      <PrototypeLinkSourceModal
+        open={linkSourceOpen}
+        onOpenChange={setLinkSourceOpen}
+        currentSourcePath={sourcePath}
+      />
+    </aside>
+  );
+}

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

@@ -1,33 +1,64 @@
 "use client";
 
 import { PrototypeProvider } from "@prototype/components/prototype-provider";
+import { PrototypeGalleryNav } from "@prototype/components/shell/prototype-gallery-nav";
 import { cn } from "@prototype/lib/utils";
 import type { ReactNode } from "react";
 
 type PrototypeGalleryShellProps = {
   children: ReactNode;
   footer?: ReactNode;
+  sourceDirectoryName?: string;
+  sourcePath?: string;
 };
 
 export function PrototypeGalleryShell({
   children,
   footer,
+  sourceDirectoryName,
+  sourcePath,
 }: PrototypeGalleryShellProps) {
   return (
-    <PrototypeProvider className="bg-[var(--bg-ground)] flex h-svh w-full flex-col overflow-hidden">
+    <PrototypeProvider className="bg-[var(--bg-main)] flex h-full min-h-0 w-full flex-1 flex-col overflow-hidden">
       {footer ? (
-        <div className="border-border 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-ground)] flex shrink-0 items-center justify-end border-b px-10 py-3 lg:px-16">
           {footer}
         </div>
       ) : null}
 
-      <main className="bg-background min-h-0 flex-1 overflow-y-auto">
-        {children}
-      </main>
+      <div className="flex h-full min-h-0 flex-1 overflow-hidden">
+        <PrototypeGalleryNav
+          sourceDirectoryName={sourceDirectoryName}
+          sourcePath={sourcePath}
+        />
+        <main className="bg-[var(--bg-main)] flex min-h-0 flex-1 flex-col overflow-hidden">
+          {children}
+        </main>
+      </div>
     </PrototypeProvider>
   );
 }
 
+type PrototypeGalleryPageLayoutProps = {
+  header: ReactNode;
+  children: ReactNode;
+};
+
+/** Gallery pages: header stays fixed; only body scrolls. */
+export function PrototypeGalleryPageLayout({
+  header,
+  children,
+}: PrototypeGalleryPageLayoutProps) {
+  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="h-fit w-full">{children}</div>
+      </div>
+    </div>
+  );
+}
+
 type PrototypeGalleryHeaderProps = {
   eyebrow?: string;
   title?: string;
@@ -44,17 +75,17 @@ export function PrototypeGalleryHeader({
   return (
     <div
       className={cn(
-        "border-border -mx-10 mb-8 border-b px-10 py-6 lg:-mx-16 lg:px-16",
+        "border-[var(--tool-chrome-border)] bg-[var(--bg-ground)] shrink-0 border-b px-10 py-6 lg:px-16",
         className,
       )}
     >
       {eyebrow ? (
-        <p className="text-xs text-muted-foreground">{eyebrow}</p>
+        <p className="text-xs text-[var(--tool-chrome-text-muted)]">{eyebrow}</p>
       ) : null}
-      <h1 className="text-foreground mt-0 text-2xl font-medium tracking-tight">
+      <h1 className="mt-0 text-2xl font-medium tracking-tight text-[var(--tool-chrome-text-heading)]">
         {title}
       </h1>
-      <p className="text-muted-foreground mt-2 max-w-2xl text-sm leading-relaxed">
+      <p className="mt-2 max-w-2xl text-sm leading-relaxed text-[var(--tool-chrome-text-muted)]">
         {description}
       </p>
     </div>
@@ -70,10 +101,11 @@ export function PrototypeGalleryPage({
 }) {
   return (
     <PrototypeGalleryShell footer={footer}>
-      <div className="px-10 lg:px-16">
-        {header ?? <PrototypeGalleryHeader />}
-        {children}
-      </div>
+      <PrototypeGalleryPageLayout
+        header={header ?? <PrototypeGalleryHeader className="mb-0" />}
+      >
+        <div className="px-10 pt-8 pb-16 lg:px-16">{children}</div>
+      </PrototypeGalleryPageLayout>
     </PrototypeGalleryShell>
   );
 }