proto-plugin 0.1.1 → 0.1.3

package/src/lib/prototypes/populate-component-library-prompt.ts

@@ -0,0 +1,64 @@
+const DEFAULT_SYNC_CONFIG_PATH = "prototype.sync.config.sh";
+const DEFAULT_COMPONENT_LIBRARY_PAGE_PATH = "src/app/component-library/page.tsx";
+
+export function buildPopulateComponentLibraryPrompt({
+  sourcePath,
+  syncConfigPath = DEFAULT_SYNC_CONFIG_PATH,
+  componentLibraryPagePath = DEFAULT_COMPONENT_LIBRARY_PAGE_PATH,
+  origin = "http://localhost:3003",
+}: {
+  sourcePath?: string;
+  syncConfigPath?: string;
+  componentLibraryPagePath?: string;
+  origin?: string;
+} = {}): string {
+  const sourceLine = sourcePath?.trim()
+    ? `- Source path: \`${sourcePath.trim()}\` (also readable via the \`source/\` symlink after \`pnpm link-source\`)`
+    : "- Source: set `SOURCE_PATH` in `.env.local`, run `pnpm link-source`, then read via the `source/` symlink";
+
+  const lines = [
+    "Populate the Component Library for this prototype host app.",
+    "",
+    "## Goal",
+    "The Component Library page is empty. Inspect the linked source application and extract all base styles and UI building blocks into this host repo.",
+    "",
+    "**Be generous — when in doubt, port more rather than less.** Prefer syncing whole directories and shared primitives over cherry-picking a minimal subset.",
+    "",
+    "## Source",
+    sourceLine,
+    "- Read the source app thoroughly before deciding what to skip.",
+    "",
+    "## What to extract (prioritize breadth)",
+    "1. Design tokens and global styles (`globals.css`, fonts, CSS variables, theme layers)",
+    "2. All shadcn/base UI primitives under `src/components/ui/`",
+    "3. Shared layout primitives, form patterns, badges, cards, tables, dialogs, and other reusable chrome",
+    "4. Shared utilities used by UI (`src/lib/utils.ts`, `cn` helpers, formatters, small hooks)",
+    "5. Composite components reused across multiple product surfaces",
+    "6. If the source organizes design-system pieces elsewhere (monorepo packages, shared folders), trace what product pages actually import and replicate those pieces here",
+    "",
+    "## How to sync",
+    "1. Ensure `SOURCE_PATH` is set in `.env.local` and run `pnpm link-source`.",
+    `2. Update \`${syncConfigPath}\` — add paths to \`SYNC_FILES\`, \`SYNC_DIRS\`, and/or \`SYNC_GLOBS\`. Prefer syncing whole directories (e.g. \`src/components/ui\`) over individual files.`,
+    "3. Run `pnpm sync-from-source`.",
+    "4. Re-apply any entries listed in `SYNC_LOCAL_EXTENSIONS` if this host customizes beyond source.",
+    "",
+    "## Component Library page",
+    `After syncing, wire live previews on \`${componentLibraryPagePath}\` via \`createPrototypeComponentLibraryPage\` so each primitive and composite is visible with common variants and states.`,
+    "",
+    `Gallery: ${origin}/component-library`,
+    "",
+    "## Rules",
+    "- Follow AGENTS.md — no runtime imports from `source/`; replicate into the host tree.",
+    "- Preserve semantic tokens from `globals.css`; avoid hardcoded hex.",
+    "- Confirm components render correctly on `/component-library` before finishing.",
+  ];
+
+  return lines.join("\n");
+}
+
+export function buildPopulateComponentLibraryCopyText(
+  options: Parameters<typeof buildPopulateComponentLibraryPrompt>[0] = {},
+): string {
+  const prompt = buildPopulateComponentLibraryPrompt(options);
+  return 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/prototype-config-types.ts

@@ -9,6 +9,8 @@ export type PrototypeDefinition = {
   screenshot: string;
   component: ComponentType;
   componentRegistry: PrototypeComponentRegistry;
+  /** Full-page state map at `/prototypes/<slug>/states`. Omit to show the default empty map. */
+  stateMapComponent?: ComponentType;
 };
 
 export type PrototypeExtraRoute = {

package/src/lib/prototypes/prototype-layout-classes.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical Tailwind fill classes for prototype pages inside #prototype-viewport.
+ * The preview shell only auto-sizes direct children of .viewportPage — every nested
+ * layer must repeat this chain or content pins to a corner and clips.
+ *
+ * @see packages/prototype/AGENTS.md — "Prototype viewport fill"
+ */
+
+/** `PrototypeComponent` with id="scroll-container" */
+export const PROTOTYPE_SCROLL_CONTAINER_CLASS =
+  "flex h-full min-h-0 flex-1 flex-col overflow-hidden";
+
+/** `PrototypeComponent` with id="page" */
+export const PROTOTYPE_PAGE_CLASS =
+  "relative flex h-full min-h-0 flex-1 flex-col overflow-hidden";
+
+/** Step/view roots, AnimatePresence wrappers, motion.div page shells */
+export const PROTOTYPE_VIEW_SHELL_CLASS =
+  "flex h-full min-h-0 w-full flex-1 flex-col overflow-hidden";

package/src/lib/prototypes/prototype-preview-state-registry.ts

@@ -212,8 +212,11 @@ export function buildPreviewStateCanvasLayout<T extends string>(
   };
 }
 
-function resolvePreviewStateRegistryLayout<TPrimary extends string>(
-  registry: PrototypePreviewStateRegistry<TPrimary>,
+function resolvePreviewStateRegistryLayout<
+  TPrimary extends string,
+  TVariant extends string = never,
+>(
+  registry: PrototypePreviewStateRegistry<TPrimary, TVariant>,
 ): {
   states: ResolvedPrototypePreviewStateDefinition<TPrimary>[];
   sections: PrototypeStateCanvasSection[];

package/src/lib/prototypes/prototype-review-context.tsx

@@ -732,8 +732,8 @@ export function PrototypeReviewProvider({
     showProdReference,
   ]);
 
-  const value = useMemo(
-    () => ({
+  const value = useMemo(() => {
+    return {
       slug,
       open,
       sidebarPanel,
@@ -806,8 +806,8 @@ export function PrototypeReviewProvider({
       viewportLayout,
       setViewportLayout,
       toggleViewportLayout,
-    }),
-    [
+    };
+  }, [
       slug,
       open,
       sidebarPanel,

package/src/lib/prototypes/prototype-state-canvas-constants.ts

@@ -85,7 +85,7 @@ export function getStateCanvasNodeHeight(
   const count = callouts?.length ?? 0;
   if (count === 0) return bodyHeight;
 
-  const calloutsHeight = callouts.reduce((sum, callout, index) => {
+  const calloutsHeight = (callouts ?? []).reduce((sum, callout, index) => {
     const gap = index > 0 ? PROTOTYPE_STATE_NODE_CALLOUT_GAP : 0;
     return sum + gap + getStateCanvasCalloutHeight(callout);
   }, 0);

package/src/lib/prototypes/prototype-state-canvas-types.ts

@@ -75,8 +75,6 @@ export type StateMapHighlightRect = {
 };
 
 export type PrototypeStateCanvasConfig<T extends string = string> = {
-  /** When omitted, no node appears selected — the map is a stateless picker. */
-  activeStateId?: T;
   onStateSelect: (id: T) => void;
   nodes: PrototypeStateCanvasNode<T>[];
   edges: PrototypeStateCanvasEdge<T>[];

package/src/lib/prototypes/prototype-storage-status.ts

@@ -0,0 +1,31 @@
+export type PrototypeStorageStatusSlice = {
+  configured: boolean;
+  missing: string[];
+};
+
+export type PrototypeStorageStatus = {
+  comments: PrototypeStorageStatusSlice;
+  gallery: {
+    kvConfigured: boolean;
+    storageConfigured: boolean;
+    missing: string[];
+  };
+};
+
+export const PROTOTYPE_STORAGE_STATUS_PATH = "/api/prototypes/storage-status";
+
+export async function fetchPrototypeStorageStatus(): Promise<PrototypeStorageStatus> {
+  const response = await fetch(PROTOTYPE_STORAGE_STATUS_PATH);
+
+  if (!response.ok) {
+    throw new Error("Failed to check prototype storage status.");
+  }
+
+  return (await response.json()) as PrototypeStorageStatus;
+}
+
+export function isPrototypeStorageFullyConfigured(
+  status: PrototypeStorageStatus,
+): boolean {
+  return status.comments.configured && status.gallery.storageConfigured;
+}

package/src/lib/prototypes/sort-prototypes-by-creation-date.ts

@@ -0,0 +1,43 @@
+import { stat } from "fs/promises";
+import path from "path";
+
+import type { PrototypeMetadata } from "./prototype-config-types";
+
+async function getPrototypeCreationMs(
+  slug: string,
+  configIndex: number,
+): Promise<number> {
+  try {
+    const stats = await stat(
+      path.join(process.cwd(), "src/prototypes", slug),
+    );
+    if (stats.birthtimeMs > 0) return stats.birthtimeMs;
+  } catch {
+    // Prototype directory may not exist in some host layouts.
+  }
+
+  // Config order is append-only — use registration index when birthtime is unavailable.
+  return configIndex;
+}
+
+export async function sortPrototypesByCreationDate(
+  prototypes: PrototypeMetadata[],
+): Promise<PrototypeMetadata[]> {
+  const creationMsBySlug = new Map<string, number>();
+
+  await Promise.all(
+    prototypes.map(async (prototype, configIndex) => {
+      creationMsBySlug.set(
+        prototype.slug,
+        await getPrototypeCreationMs(prototype.slug, configIndex),
+      );
+    }),
+  );
+
+  return [...prototypes].sort((a, b) => {
+    const creationDiff =
+      (creationMsBySlug.get(b.slug) ?? 0) - (creationMsBySlug.get(a.slug) ?? 0);
+    if (creationDiff !== 0) return creationDiff;
+    return a.title.localeCompare(b.title);
+  });
+}

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/lib/prototypes/use-prototype-tool-theme.tsx

@@ -28,7 +28,7 @@ type PrototypeToolThemeContextValue = {
 const PrototypeToolThemeContext =
   createContext<PrototypeToolThemeContextValue | null>(null);
 
-const DEFAULT_THEME: PrototypeToolTheme = "dark";
+const DEFAULT_THEME: PrototypeToolTheme = "light";
 
 function normalizeTheme(value: string): PrototypeToolTheme {
   return value === "light" ? "light" : "dark";

package/src/lib/prototypes/use-toolbar-hover-panel.ts

@@ -8,12 +8,21 @@ import type {
 
 export const TOOLBAR_PANEL_HOVER_OPEN_DELAY_MS = 100;
 export const TOOLBAR_PANEL_HOVER_CLOSE_DELAY_MS = 150;
+export const TOOLBAR_HOVER_CAPABLE_MEDIA_QUERY =
+  "(hover: hover) and (pointer: fine)";
+
+export function supportsToolbarHover() {
+  if (typeof window === "undefined") return true;
+  return window.matchMedia(TOOLBAR_HOVER_CAPABLE_MEDIA_QUERY).matches;
+}
 
 export function preventToolbarHoverButtonActivation(
   event:
     | ReactMouseEvent<HTMLButtonElement>
     | ReactPointerEvent<HTMLButtonElement>,
 ) {
+  if (!supportsToolbarHover()) return;
+
   event.preventDefault();
   event.stopPropagation();
 }
@@ -59,7 +68,7 @@ export function useToolbarHoverPanel({
 
   const scheduleOpen = useCallback(
     (event: ReactPointerEvent<HTMLElement>) => {
-      if (event.pointerType === "touch") return;
+      if (!supportsToolbarHover() || event.pointerType === "touch") return;
 
       clearCloseTimer();
       clearOpenTimer();
@@ -71,6 +80,8 @@ export function useToolbarHoverPanel({
   );
 
   const scheduleClose = useCallback(() => {
+    if (!supportsToolbarHover()) return;
+
     clearOpenTimer();
     clearCloseTimer();
     closeTimerRef.current = setTimeout(() => {

package/src/lib/prototypes/variant-set-lucide-icon.tsx

@@ -1,14 +1,24 @@
 import type { LucideIcon, LucideProps } from "lucide-react";
 import {
   ArrowDownUp,
+  BadgeCheck,
   CalendarDays,
   Clock,
   FilterX,
+  Hexagon,
   Inbox,
   LayoutGrid,
+  LayoutList,
+  LayoutTemplate,
+  PanelsTopLeft,
+  MessageSquareText,
+  Palette,
   PanelBottom,
+  PanelBottomOpen,
+  Send,
   Shapes,
   Smartphone,
+  Sparkles,
   Table,
 } from "lucide-react";
 
@@ -19,6 +29,20 @@ type VariantSetIconRule = {
 
 /** First match wins — order rules from most specific to broadest. */
 const VARIANT_SET_ICON_RULES: VariantSetIconRule[] = [
+  { test: /event-types-page-layout|event types page layout/i, icon: PanelsTopLeft },
+  // proto-partner-page explorations
+  { test: /creator-attribution|creator attribution/i, icon: BadgeCheck },
+  { test: /submit-modal|submit modal/i, icon: Send },
+  { test: /mobile-panel-motion|mobile panel motion/i, icon: PanelBottomOpen },
+  { test: /mobile-picker-layout|mobile picker layout/i, icon: LayoutList },
+  {
+    test: /invite-follow-up-shape-layout|follow-up shape layout/i,
+    icon: LayoutTemplate,
+  },
+  { test: /invite-animations|invite animations/i, icon: Sparkles },
+  { test: /shape-color-picker|shape & color picker/i, icon: Palette },
+  { test: /proto-shapes|proto shapes/i, icon: Hexagon },
+  { test: /invite-copy|invite copy/i, icon: MessageSquareText },
   { test: /retention|expir|before/i, icon: Clock },
   { test: /calendar|date.?picker|date-range/i, icon: CalendarDays },
   { test: /mobile/i, icon: Smartphone },

package/src/lib/tool-portal.ts

@@ -8,6 +8,9 @@ export const PROTOTYPE_VIEWPORT_ID = "prototype-viewport";
 
 export const PROTOTYPE_SCREENSHOT_ATTR = "data-prototype-screenshot";
 
+/** Synced source-app previews (component library, etc.) — fixed product tokens, not tool theme. */
+export const PROTOTYPE_SOURCE_SURFACE_ATTR = "data-prototype-source-surface";
+
 export const PROTOTYPE_COMMENTS_SIDEBAR_ROOT_ID =
   "prototype-comments-sidebar-root";
 
@@ -16,6 +19,27 @@ export function getPrototypePortalContainer(): HTMLElement | undefined {
   return document.getElementById(PROTOTYPE_ROOT_ID) ?? undefined;
 }
 
+/** Dialogs/overlays inside prototype content — scoped to the preview viewport, not the review sidebar. */
+export function getPrototypeDialogPortalContainer(): HTMLElement | undefined {
+  if (typeof document === "undefined") return undefined;
+  return (
+    document.getElementById(PROTOTYPE_VIEWPORT_ID) ??
+    document.getElementById(PROTOTYPE_PREVIEW_STAGE_ID) ??
+    document.getElementById(PROTOTYPE_ROOT_ID) ??
+    undefined
+  );
+}
+
+/** Tool chrome modals (prompt copy, link source, etc.) — outside the screenshot surface so dark/light tool theme applies. */
+export function getPrototypeToolDialogPortalContainer(): HTMLElement | undefined {
+  if (typeof document === "undefined") return undefined;
+  return (
+    document.getElementById(PROTOTYPE_ROOT_ID) ??
+    document.getElementById(PROTOTYPE_PREVIEW_STAGE_ID) ??
+    undefined
+  );
+}
+
 export function getPrototypePreviewStage(): HTMLElement | undefined {
   if (typeof document === "undefined") return undefined;
   return document.getElementById(PROTOTYPE_PREVIEW_STAGE_ID) ?? undefined;

package/src/lib/use-copy-to-clipboard.ts

@@ -1,9 +1,9 @@
 "use client";
 
+import { copyTextWithAttachments } from "@prototype/lib/copy-text-with-attachments";
 import { cn } from "@prototype/lib/utils";
 import { CheckIcon, CopyIcon, SaveIcon } from "lucide-react";
 import { createElement, useCallback, useRef, useState } from "react";
-import { toast } from "sonner";
 
 type CopyState = "idle" | "scaling-out" | "copied" | "reverting-out" | null;
 
@@ -25,7 +25,7 @@ export default function useCopyToClipboard({
   const isCopied = state === "copied" || state === "reverting-out";
 
   const copy = useCallback(
-    (text: string) => {
+    async (text: string) => {
       clearTimeout(timerRef.current);
       setState("idle");
 
@@ -43,17 +43,11 @@ export default function useCopyToClipboard({
         timerRef.current = setTimeout(revert, cooldownTime);
       };
 
-      navigator.clipboard
-        .writeText(text)
-        .catch(() => {
-          toast.error("Copy error", {
-            description: "Failed to copy value to clipboard",
-          });
-        })
-        .finally(() => {
-          setState("scaling-out");
-          timerRef.current = setTimeout(copied, SCALE_OUT_MS);
-        });
+      const didCopy = await copyTextWithAttachments(text);
+      if (!didCopy) return;
+
+      setState("scaling-out");
+      timerRef.current = setTimeout(copied, SCALE_OUT_MS);
     },
     [cooldownTime],
   );

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

@@ -6,10 +6,11 @@ import {
   createPrototypeChangelogMetaRoute,
   createPrototypeCommentIdRoute,
   createPrototypeCommentsRoute,
-  createPrototypeDesignExplorationDefaultRoute,
   createPrototypeScreenshotRoute,
 } 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 = {
@@ -20,8 +21,6 @@ export function createPrototypeApiRoute(_config: PrototypeConfig) {
   const commentsRoute = createPrototypeCommentsRoute(_config);
   const commentIdRoute = createPrototypeCommentIdRoute(_config);
   const changelogMetaRoute = createPrototypeChangelogMetaRoute(_config);
-  const designExplorationDefaultRoute =
-    createPrototypeDesignExplorationDefaultRoute(_config);
   const screenshotRoute = createPrototypeScreenshotRoute(_config);
   const galleryApi =
     _config.gallery === false ? null : createGalleryApi(_config.gallery);
@@ -44,6 +43,18 @@ 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();
+      }
+    }
+
     if (path[0] === "prototypes" && path.length >= 2) {
       const slug = path[1]!;
 
@@ -72,19 +83,6 @@ export function createPrototypeApiRoute(_config: PrototypeConfig) {
         }
       }
 
-      if (path.length === 3 && path[2] === "design-exploration-default") {
-        if (method === "GET") {
-          return designExplorationDefaultRoute.GET(request, {
-            params: Promise.resolve({ slug }),
-          });
-        }
-        if (method === "PUT") {
-          return designExplorationDefaultRoute.PUT(request, {
-            params: Promise.resolve({ slug }),
-          });
-        }
-      }
-
       if (path.length === 3 && path[2] === "screenshot" && method === "POST") {
         return screenshotRoute.POST(request, { params: Promise.resolve({ slug }) });
       }