proto-plugin 0.1.0 → 0.1.2

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/comment-storage-setup-prompt.ts

@@ -0,0 +1,124 @@
+export const COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE =
+  "Comment storage is not configured. Set Upstash Redis and Vercel Blob env vars.";
+
+export function isCommentStorageSetupError(message: string | null | undefined): boolean {
+  if (!message) return false;
+  return (
+    message.includes("not configured") ||
+    message.includes("Upstash Redis") ||
+    message.includes("Vercel Blob") ||
+    message.includes("KV_REST") ||
+    message.includes("BLOB_")
+  );
+}
+
+export type CommentStorageSetupPromptOptions = {
+  vercelProjectName?: string;
+  vercelTeamSlug?: string;
+};
+
+export function buildCommentStorageSetupPrompt({
+  vercelProjectName = "proto-plugin",
+  vercelTeamSlug = "maayan-alberts-projects",
+}: CommentStorageSetupPromptOptions = {}): string {
+  const upstashTermsUrl = `https://vercel.com/${vercelTeamSlug}/~/integrations/accept-terms/upstash?source=cli`;
+
+  return [
+    "Set up prototype storage (Upstash Redis + Vercel Blob) for this host app. **Do every step yourself** — the user should not run commands manually.",
+    "",
+    "## Your job",
+    "Provision both stores on Vercel, pull env vars locally, restart dev, and confirm Comments + gallery storage work. Only stop to ask the user when a browser step is unavoidable (marketplace terms).",
+    "",
+    "## Vercel project",
+    `- Project: \`${vercelProjectName}\``,
+    `- Team: \`${vercelTeamSlug}\``,
+    "",
+    "## Step 1 — Link the repo (skip if \`.vercel/project.json\` exists)",
+    "```bash",
+    `npx vercel link --yes --project ${vercelProjectName} --scope ${vercelTeamSlug}`,
+    "```",
+    "",
+    "## Step 2 — Accept Upstash marketplace terms (browser — ask user once)",
+    "If `vercel integration add` returns `integration_terms_acceptance_required`, send the user this URL and wait for confirmation before retrying:",
+    upstashTermsUrl,
+    "",
+    "## Step 3 — Install Upstash Redis",
+    "```bash",
+    "npx vercel integration add upstash/upstash-kv -m primaryRegion=sfo1 -p free -n proto-plugin-redis",
+    "```",
+    "",
+    "Connect to **development**, **preview**, and **production** (default when prompted with `--yes`).",
+    "",
+    "## Step 4 — Create Vercel Blob store (required)",
+    "Gallery screenshots need Blob — not optional.",
+    "",
+    "```bash",
+    "npx vercel blob create-store proto-plugin-blob --access public -y -e development -e preview -e production",
+    "```",
+    "",
+    "If a store already exists, connect it to this project from Vercel → Storage, or use `vercel blob list-stores` and ensure `BLOB_READ_WRITE_TOKEN` is on the project.",
+    "",
+    "## Step 5 — Verify env vars exist on Vercel",
+    "```bash",
+    "npx vercel env ls",
+    "npx vercel integration list",
+    "```",
+    "",
+    "Required before continuing:",
+    "- `KV_REST_API_URL`",
+    "- `KV_REST_API_TOKEN`",
+    "- `BLOB_READ_WRITE_TOKEN`",
+    "",
+    "If `vercel env pull` previously only gave `VERCEL_OIDC_TOKEN`, that is CLI auth — not storage. Storage vars appear only after steps 3–4 succeed.",
+    "",
+    "## Step 6 — Pull env vars locally (required — do not skip)",
+    "`.env.local` holds host-only values like `SOURCE_PATH`. **Never** pull into `.env.local` — it overwrites that file.",
+    "",
+    "Pull development env vars into a separate file:",
+    "",
+    "```bash",
+    "npx vercel env pull .env.development.local -y",
+    "```",
+    "",
+    "Next.js loads both `.env.local` and `.env.development.local` in development.",
+    "",
+    "After pull, confirm `.env.development.local` contains `KV_REST_*` and `BLOB_READ_WRITE_TOKEN`. Leave `SOURCE_PATH` in `.env.local` untouched.",
+    "",
+    "## Step 7 — Restart dev and verify",
+    "```bash",
+    "pnpm dev",
+    "```",
+    "",
+    "Then confirm storage is configured:",
+    "",
+    "```bash",
+    "curl -s http://localhost:1985/api/prototypes/storage-status",
+    "```",
+    "",
+    "Expect:",
+    "- `comments.configured: true`",
+    "- `gallery.storageConfigured: true`",
+    "",
+    "Open a prototype → Comments sidebar should load with no setup prompt (empty list is fine).",
+    "",
+    "## Required env vars (all three)",
+    "| Var | Purpose |",
+    "| --- | --- |",
+    "| `KV_REST_API_URL` | Upstash Redis — comments, change log, gallery metadata |",
+    "| `KV_REST_API_TOKEN` | Upstash Redis token |",
+    "| `BLOB_READ_WRITE_TOKEN` | Vercel Blob — gallery screenshot uploads |",
+    "",
+    "Either `KV_*` or `UPSTASH_REDIS_REST_*` works — the app normalizes both.",
+    "",
+    "## Reference",
+    "- Env template: `.env.example`",
+    "- Storage status: `packages/prototype/src/server/prototype-storage-status-route.ts`",
+    "- Redis client: `packages/prototype/src/server/redis/client.ts`",
+  ].join("\n");
+}
+
+export function buildCommentStorageSetupCopyText(
+  options: CommentStorageSetupPromptOptions = {},
+): string {
+  return buildCommentStorageSetupPrompt(options);
+}

package/src/lib/prototypes/create-prototype-prompt.ts

@@ -0,0 +1,96 @@
+export function suggestPrototypeSlug(title: string): string {
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function buildCreatePrototypePrompt({
+  title,
+  description,
+  origin = "http://localhost:3003",
+}: {
+  title: string;
+  description: string;
+  origin?: string;
+}): string {
+  const trimmedTitle = title.trim();
+  const trimmedDescription = description.trim();
+  const suggestedSlug = suggestPrototypeSlug(trimmedTitle);
+  const galleryUrl = `${origin}/`;
+
+  const lines = [
+    `Create a new prototype: "${trimmedTitle}".`,
+    "",
+    "## Brief",
+    `- Title: ${trimmedTitle}`,
+    `- Description: ${trimmedDescription}`,
+    `- Suggested slug: \`${suggestedSlug || "my-prototype"}\` (pick a unique kebab-case slug if taken)`,
+    "",
+    "## Source app",
+    "Draw from the **source application** (linked via `SOURCE_PATH` / `pnpm link-source`) — not from other prototypes in this gallery. Replicate the page or feature named in the brief **exactly**: layout, spacing, typography, components, empty/loading/error states, and interactions. Match the source side-by-side; do not approximate or invent alternate UI.",
+    "",
+    "## Gallery",
+    galleryUrl,
+  ];
+
+  lines.push(
+    "",
+    "## Preview states (required — do not skip)",
+    "Before building UI, list every distinct mode reviewers must open directly from the State picker and `/prototypes/<slug>/states` map. Include modes implied by the brief and source page, for example:",
+    "- Primary tabs, steps, or wizard stages",
+    "- Empty, loading, and error branches",
+    "- Filter bars, preset filters, active filter chips, and add-filter popovers",
+    "- Modals, drawers, and overlay branches",
+    "- View toggles (list vs calendar, grid vs table, etc.)",
+    "",
+    "Each mode gets one registry entry in `*-preview-states.ts` with matching `liveState` in `createLiveStateForPreview`. Wire the full stack in the same pass as the UI — not as a follow-up.",
+    "",
+    "## Instructions",
+    "Follow AGENTS.md → New prototype checklist and **Live state & preview states (mandatory)**.",
+    "",
+    "1. Find the source page/feature in the linked source app, read it fully, and confirm side-by-side visual parity before finishing.",
+    "2. Create `src/prototypes/<slug>/` with a default export page component.",
+    "3. Add `component-ids.ts` — exhaustive static id list + `dynamicPrefixes`.",
+    "4. Register in `prototype.config.ts` with `componentRegistry`.",
+    "5. Wrap every UI component in `PrototypeComponent` / `PrototypeControl`.",
+    "6. Define typed `liveState`, wire `usePrototypeComments(liveState, onRestore)`, and derive all preview-relevant UI from `liveState`.",
+    "7. Add preview states in the same change (mandatory for feature pages — see **Preview states** above):",
+    "   - `src/prototypes/<slug>/_components/<slug>-preview-states.ts` — `definePreviewStateRegistry`, `createLiveStateForPreview`, one entry per mode",
+    "   - `src/prototypes/<slug>/_components/<slug>-preview-state-select.tsx` — wire `ControlsPanelSelect` with `appearance=\"menuList\"` into the review toolbar via `setTweaksContent` (no floating mini-pill on the page)",
+    "   - `src/prototypes/<slug>/_components/<slug>-state-canvas-config.tsx` — wireframes from the same registry",
+    "   - `src/prototypes/<slug>/state-map-page.tsx` — full-page state map at `/prototypes/<slug>/states`",
+    "   - `stateMapComponent` on the prototype entry in `prototype.config.ts`",
+    "   - In `index.tsx`: `review.setStateCanvasConfig(build…StateCanvasConfig(onStateSelect))` in an effect — pass only the select handler, not `liveState` or the current preview mode (state map is stateless; always light mode)",
+    "8. Run `pnpm verify:prototype-ids` and `pnpm verify:prototype-preview-states`.",
+    "9. Capture a screenshot under `public/prototypes/screenshots/`; share via `pnpm share-prototype <slug>`.",
+    "",
+    "Reference: `src/prototypes/booking-flow/` (`index.tsx`, `*-preview-states.ts`, `*-preview-state-select.tsx`, `*-state-canvas-config.tsx`, `state-map-page.tsx`, `prototype.config.ts` → `stateMapComponent`).",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildCreatePrototypeCopyText({
+  title,
+  description,
+  origin = "http://localhost:3003",
+}: {
+  title: string;
+  description: string;
+  origin?: string;
+}): string {
+  const trimmedTitle = title.trim();
+  const trimmedDescription = description.trim();
+  const brief = [`Title: ${trimmedTitle}`, `Description: ${trimmedDescription}`].join(
+    "\n",
+  );
+  const prompt = buildCreatePrototypePrompt({
+    title: trimmedTitle,
+    description: trimmedDescription,
+    origin,
+  });
+
+  return `${brief}\n\n---\n\n${prompt}`;
+}

package/src/lib/prototypes/create-prototype-registry.ts

@@ -40,6 +40,11 @@ export function createPrototypeRegistry(config: PrototypeConfig) {
         ?.component;
     },
 
+    getPrototypeStateMapComponent(slug: string) {
+      return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+        ?.stateMapComponent;
+    },
+
     getPrototypeComponentRegistryForSlug(
       slug: string,
     ): PrototypeComponentRegistry | undefined {