proto-plugin 0.1.1 → 0.1.3

package/src/config/create-prototype-state-map-page.tsx

@@ -0,0 +1,44 @@
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+
+import { PrototypeDefaultStateMapPage } from "@prototype/components/prototypes/prototype-default-state-map-page";
+import { PrototypeShell } from "@prototype/components/shell/prototype-shell";
+import { createPrototypeRegistry } from "@prototype/lib/prototypes/create-prototype-registry";
+import type { PrototypeConfig } from "@prototype/lib/prototypes/prototype-config-types";
+
+type PrototypeStateMapPageProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export function createPrototypeStateMapPage(config: PrototypeConfig) {
+  const registry = createPrototypeRegistry(config);
+
+  function generateStaticParams() {
+    return registry.getAllPrototypes().map(({ slug }) => ({ slug }));
+  }
+
+  async function PrototypeStateMapPage({ params }: PrototypeStateMapPageProps) {
+    const { slug } = await params;
+    const prototype = registry.getPrototype(slug);
+    const StateMapComponent = registry.getPrototypeStateMapComponent(slug);
+    const componentRegistry = registry.getPrototypeComponentRegistryForSlug(slug);
+
+    if (!prototype) {
+      notFound();
+    }
+
+    return (
+      <Suspense fallback={null}>
+        <PrototypeShell slug={slug} componentRegistry={componentRegistry}>
+          {StateMapComponent ? (
+            <StateMapComponent />
+          ) : (
+            <PrototypeDefaultStateMapPage slug={slug} />
+          )}
+        </PrototypeShell>
+      </Suspense>
+    );
+  }
+
+  return { default: PrototypeStateMapPage, generateStaticParams };
+}

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

@@ -1,34 +1,51 @@
 "use client";
 
+import { PrototypePluginUpdatePopup } from "@prototype/components/shell/prototype-plugin-update-popup";
 import { usePathname } from "next/navigation";
 import type { ComponentType, ReactNode } from "react";
 
 type PrototypeSiteLayoutClientProps = {
   children: ReactNode;
-  galleryShell: ComponentType<{ children: ReactNode }>;
+  galleryShell: ComponentType<{
+    children: ReactNode;
+    sourceDirectoryName?: string;
+    sourcePath?: string;
+  }>;
+  sourceDirectoryName?: string;
+  sourcePath?: string;
   toaster: ReactNode;
 };
 
 export function PrototypeSiteLayoutClient({
   children,
   galleryShell: GalleryShell,
+  sourceDirectoryName,
+  sourcePath,
   toaster,
 }: PrototypeSiteLayoutClientProps) {
   const pathname = usePathname();
-  const isGalleryHome = pathname === "/";
+  const isGalleryRoute =
+    pathname === "/" || pathname.startsWith("/component-library");
 
-  if (isGalleryHome) {
+  if (isGalleryRoute) {
     return (
-      <>
-        <GalleryShell>{children}</GalleryShell>
+      <div className="bg-[var(--bg-main)] flex h-svh min-h-svh w-full flex-col overflow-hidden">
+        <GalleryShell
+          sourceDirectoryName={sourceDirectoryName}
+          sourcePath={sourcePath}
+        >
+          {children}
+        </GalleryShell>
+        <PrototypePluginUpdatePopup />
         {toaster}
-      </>
+      </div>
     );
   }
 
   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,16 +8,67 @@ 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,
+    // Next.js 16 blocks cross-origin dev asset/HMR requests by default.
+    // Include ngrok (mobile testing) and common local host aliases (Glass browser, 127.0.0.1).
+    allowedDevOrigins: [
+      ...(nextConfig.allowedDevOrigins ?? []),
+      "127.0.0.1",
+      "[::1]",
+      "*.ngrok-free.app",
+      "*.ngrok-free.dev",
+      "*.ngrok.app",
+      "*.ngrok.io",
+      "*.ngrok.dev",
+    ],
     transpilePackages: [
       ...(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: [
+        {
+          pathname: "/prototypes/screenshots/**",
+        },
+        ...(nextConfig.images?.localPatterns ?? []),
+      ],
+    },
   };
 }

package/src/index.ts

@@ -1,7 +1,14 @@
 export { definePrototypeConfig } from "./config/define-prototype-config";
+// 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,
@@ -44,26 +51,76 @@ export type { PrototypeVercelPreviewModalProps } from "./components/prototypes/p
 export { PrototypeTweaks } from "./components/prototypes/prototype-tweaks";
 export type { PrototypeTweakConfig } from "./components/prototypes/prototype-tweaks";
 
+export {
+  PROTOTYPE_PAGE_CLASS,
+  PROTOTYPE_SCROLL_CONTAINER_CLASS,
+  PROTOTYPE_VIEW_SHELL_CLASS,
+} from "./lib/prototypes/prototype-layout-classes";
+
 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,
 } from "./lib/prototypes/use-persisted-local-state";
 
-export type { DesignExplorationConfig } from "./lib/prototypes/design-exploration-types";
+export type {
+  DesignExplorationBaselineOption,
+  DesignExplorationConfig,
+  DesignExplorationRationale,
+  MobbinReference,
+} from "./lib/prototypes/design-exploration-types";
 
 export {
   buildCreateDesignExplorationCopyText,
   buildCreateDesignExplorationPrompt,
+  buildMoreDesignExplorationVariantsCopyText,
+  buildMoreDesignExplorationVariantsPrompt,
   buildResetBriefDefaultsPrompt,
+  DESIGN_EXPLORATION_BASELINE_LABEL,
   getAdjacentDesignExplorationVariant,
+  getDesignExplorationDisplayOptions,
+  getDesignExplorationVariantOptions,
+  resolveDesignExplorationBaselineOption,
 } from "./lib/prototypes/design-exploration-types";
 
+export { buildDesignExplorationRenderers } from "./lib/prototypes/build-design-exploration-renderers";
+
+export {
+  DesignExplorationVariantPreviewShell,
+  type DesignExplorationVariantPreviewLayout,
+  type DesignExplorationVariantPreviewShellProps,
+} from "./components/prototypes/design-exploration-variant-preview-shell";
+
 export {
   buildCreatePreviewStateCopyText,
   buildCreatePreviewStatePrompt,
 } from "./lib/prototypes/prototype-preview-state-types";
+
+export {
+  buildCreatePrototypeCopyText,
+  buildCreatePrototypePrompt,
+  suggestPrototypeSlug,
+} from "./lib/prototypes/create-prototype-prompt";
+
+export {
+  buildPopulateComponentLibraryCopyText,
+  buildPopulateComponentLibraryPrompt,
+} from "./lib/prototypes/populate-component-library-prompt";
+export {
+  buildLinkSourceCopyText,
+  buildLinkSourcePrompt,
+} from "./lib/prototypes/link-source-prompt";
 export type { PrototypePreviewState } from "./lib/prototypes/prototype-preview-state-types";
 
 export {
@@ -113,6 +170,7 @@ export {
   PrototypeGalleryShell,
   PrototypeGalleryHeader,
   PrototypeGalleryPage,
+  PrototypeGalleryPageLayout,
 } from "./components/shell/prototype-gallery-shell";
 
 export { screenshotSrc } from "./lib/prototypes/screenshot-src";
@@ -225,8 +283,11 @@ export {
   PROTOTYPE_PREVIEW_STAGE_ID,
   PROTOTYPE_ROOT_ID,
   PROTOTYPE_SCREENSHOT_ATTR,
+  PROTOTYPE_SOURCE_SURFACE_ATTR,
   PROTOTYPE_VIEWPORT_ID,
   getPrototypeChromeRoot,
+  getPrototypeDialogPortalContainer,
+  getPrototypeToolDialogPortalContainer,
   getPrototypePreviewStage,
   getPrototypeScreenshotRoot,
 } from "./lib/tool-portal";
@@ -246,15 +307,6 @@ export {
   useChangelogMetaOptional,
 } from "./lib/prototypes/changelog-meta-context";
 
-export {
-  prototypeDesignExplorationDefaultRedisKey,
-  parseDesignExplorationDefault,
-  isValidDesignExplorationDefaultRecord,
-} from "./lib/prototypes/design-exploration-default";
-export type { DesignExplorationDefaultRecord } from "./lib/prototypes/design-exploration-default";
-export { createDesignExplorationDefaultStorageAdapter } from "./lib/prototypes/design-exploration-default-storage";
-export { useDesignExplorationDefault } from "./lib/prototypes/use-design-exploration-default";
-
 export {
   filterAnnotationsByChannel,
   getChangelogRootAnnotations,
@@ -276,10 +328,18 @@ export type { PrototypeSpecPanelContentProps } from "./components/prototypes/pro
 export {
   PR_TARGET_HIGHLIGHT_BORDER,
   PR_TARGET_HIGHLIGHT_FILL,
+  PR_SPLIT_WIREFRAME_FRAME_CLASS,
 } from "./lib/pr-split/pr-split-highlight";
 
 export { buildPrSplitPrototypeUrl } from "./lib/pr-split/build-pr-split-prototype-url";
 export { buildPrAgentPrompt } from "./lib/pr-split/build-pr-agent-prompt";
+export {
+  buildPrSplitPlanPrompt,
+  buildPrSplitPlanCopyText,
+} from "./lib/pr-split/build-pr-split-plan-prompt";
+export type { PrSplitPlanPromptOptions } from "./lib/pr-split/build-pr-split-plan-prompt";
+
+export { PrototypeSpecPanelEmptyState } from "./components/prototypes/prototype-spec-panel-empty-state";
 
 export type {
   PrSplitEntry,

package/src/lib/copy-text-with-attachments.ts

@@ -0,0 +1,35 @@
+import { toast } from "sonner";
+
+function copyTextWithExecCommand(text: string): boolean {
+  try {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.left = "-9999px";
+    textarea.style.top = "0";
+    document.body.appendChild(textarea);
+    textarea.select();
+    const ok = document.execCommand("copy");
+    document.body.removeChild(textarea);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyTextWithAttachments(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    if (copyTextWithExecCommand(text)) {
+      return true;
+    }
+
+    toast.error("Copy error", {
+      description: "Failed to copy prompt to clipboard",
+    });
+    return false;
+  }
+}

package/src/lib/format-source-directory-name.ts

@@ -0,0 +1,12 @@
+/** Last path segment of SOURCE_PATH for gallery chrome, e.g. `/path/to/proto-site` → `proto-site`. */
+export function formatSourceDirectoryName(
+  sourcePath: string | undefined,
+): string | undefined {
+  const trimmed = sourcePath?.trim();
+  if (!trimmed) return undefined;
+
+  const normalized = trimmed.replace(/[/\\]+$/, "");
+  const segments = normalized.split(/[/\\]/);
+  const name = segments.at(-1);
+  return name || undefined;
+}

package/src/lib/platform-ui/sidebar-interactive-cursor.ts

@@ -0,0 +1,19 @@
+/** Interactive targets inside review/platform sidebars that should show pointer. */
+export const SIDEBAR_INTERACTIVE_POINTER_SELECTOR =
+  ":is(button:not(:disabled), [role='button']:not([aria-disabled='true']), a[href], summary, label:has([role='switch']), label:has(input[type='checkbox']))";
+
+export const SIDEBAR_ROOT_SELECTORS = [
+  "[data-prototype-review-sidebar]",
+  "[data-comments-sidebar]",
+  "[data-platform-sidebar]",
+  "#prototype-comments-sidebar-root",
+] as const;
+
+export function buildSidebarInteractivePointerCss(options?: {
+  important?: boolean;
+}): string {
+  const suffix = options?.important ? " !important" : "";
+  return SIDEBAR_ROOT_SELECTORS.map(
+    (root) => `${root} ${SIDEBAR_INTERACTIVE_POINTER_SELECTOR}`,
+  ).join(",\n") + ` { cursor: pointer${suffix}; }`;
+}

package/src/lib/pr-split/build-pr-split-plan-prompt.ts

@@ -0,0 +1,81 @@
+export type PrSplitPlanPromptOptions = {
+  slug: string;
+  origin?: string;
+  sourceRepo?: string;
+  sourceWorkPath?: string;
+};
+
+export function buildPrSplitPlanPrompt({
+  slug,
+  origin = "http://localhost:1985",
+  sourceRepo = "calcom/cal.diy",
+  sourceWorkPath = "apps/web",
+}: PrSplitPlanPromptOptions): string {
+  const prototypePath = `src/prototypes/${slug}/`;
+  const configPath = `${prototypePath}_components/pr-split-config.ts`;
+  const wireframesPath = `${prototypePath}_components/pr-split-wireframes.tsx`;
+  const previewUrl = `${origin}/prototypes/${slug}?reviewPanel=spec`;
+
+  return [
+    `Create a PR split spec for the \`${slug}\` prototype. **First identify everything that changed**, then propose a merge-ordered PR plan and implement the spec in this repo.`,
+    "",
+    "## Phase 1 — Audit what changed",
+    "",
+    "1. Read the prototype at `" + prototypePath + "` — especially `index.tsx`, any `*-preview-states.ts`, all `*-design-exploration-config.tsx` files, mock data, and `component-ids.ts`.",
+    "2. For each design exploration, compare the **baseline** option (marked **Original** in the brief) to the **default variant** in code (`DEFAULT_*_VARIANT` constants). Baselines = production / pre-exploration UI; defaults = chosen shipping direction.",
+    "3. Compare against production in the source app (`SOURCE_PATH` / `source/` symlink, repo `" + sourceRepo + "`). Find the real page under `" + sourceWorkPath + "` and list layout, behavior, and data-model deltas.",
+    "4. Run `git log` and `git diff` on `" + prototypePath + "` to capture the full change history (including uncommitted work).",
+    "5. Read preview states in `*-preview-states.ts` — each distinct reviewer mode may map to a PR slice.",
+    "6. Note explorations that should **stay in the design brief only** (alternate layout or entry-point variants not chosen for shipping).",
+    "",
+    "## Phase 2 — Plan the PR breakdown",
+    "",
+    "Propose **3–7 small, merge-ordered PRs** for `" + sourceRepo + "`. For each PR, define:",
+    "",
+    "- `order`, `title`, `description` (2–3 sentences of source-repo work)",
+    "- `size` (`Small` | `Medium` | `Large`)",
+    "- `targetId` — one registered id from `component-ids.ts`",
+    "- `wireframeId` — key for a full-page schematic wireframe renderer",
+    "- `liveState` — restores the prototype preview for that slice",
+    "- Dependencies on earlier PRs in the series",
+    "",
+    "Grouping guidance:",
+    "- Ship data / filter logic before UI entry points that depend on it",
+    "- Keep the primary layout change as its own PR",
+    "- Empty states, modals, and polish can follow once foundation PRs land",
+    "- Do not bundle unrelated design-brief alternates into shipping PRs",
+    "",
+    "Present the plan as a numbered list with a short dependency diagram before implementing.",
+    "",
+    "## Phase 3 — Implement the PR split spec (this repo)",
+    "",
+    "Follow `packages/prototype/AGENTS.md` → **PR split specs**:",
+    "",
+    "1. Create `" + configPath + "` with `PR_SPLIT_CONFIG` and `PR_SPLIT_ENTRIES`",
+    "   - `slug: \"" + slug + "\"`",
+    "   - `sourceRepo: \"" + sourceRepo + "\"`, `sourceWorkPath: \"" + sourceWorkPath + "\"`",
+    "   - `writeEntryToSearchParams` restores each entry's `liveState`",
+    "   - `scopeNote` guardrail: do not ship unchosen design-brief variants",
+    "2. Create `" + wireframesPath + "` — full-page schematic wireframes (see **Wireframe rules** below)",
+    "3. Wire `" + prototypePath + "index.tsx` — parse/sync `?prSplit=`, call `setSpecContent(<PrototypeSpecPanelContent ...>)`, `handlePrNavigate` with `focusShareTarget`",
+    "4. Update `component-ids.ts` — add `spec-panel-content`, wireframe ids, etc.",
+    "5. Verify each PR card restores the correct prototype state and highlights the right component",
+    "",
+    "### Wireframe rules (mandatory)",
+    "",
+    "Each PR card preview must show the **full prototype page shell** — sidebar, header/toolbar, and main content area as reviewers see them in the live preview. Do **not** draw cropped excerpts, zoomed-in component slices, or short strips that only show the changed region.",
+    "",
+    "- Scaffold every wireframe from the prototype's real page layout (match the shell layout component)",
+    "- Use low-fidelity `Wire` blocks; apply `PR_TARGET_HIGHLIGHT_BORDER` / `PR_TARGET_HIGHLIGHT_FILL` only on the PR target",
+    "- Fill the card preview area: wrap the wireframe root in `PR_SPLIT_WIREFRAME_FRAME_CLASS` (`aspect-video w-full overflow-hidden`) so the schematic reads as a full screen, not a tiny excerpt",
+    "- The highlight shows where the slice lands on the page; surrounding chrome provides context",
+    "",
+    "Prototype preview: " + previewUrl,
+    "",
+    "After the spec is wired, summarize the final PR sequence for the user. Do not open source PRs until the plan is approved.",
+  ].join("\n");
+}
+
+export function buildPrSplitPlanCopyText(options: PrSplitPlanPromptOptions): string {
+  return buildPrSplitPlanPrompt(options);
+}

package/src/lib/pr-split/pr-split-highlight.ts

@@ -4,3 +4,6 @@ export const PR_TARGET_HIGHLIGHT_BORDER =
 
 export const PR_TARGET_HIGHLIGHT_FILL =
   "color-mix(in srgb, var(--prototype-comment-color-blue) 6%, transparent)";
+
+/** Root wrapper for PR split wireframes — full-page schematic, not a cropped excerpt. */
+export const PR_SPLIT_WIREFRAME_FRAME_CLASS = "aspect-video w-full overflow-hidden";

package/src/lib/prototype-comments/core/annotation-target.ts

@@ -1,4 +1,5 @@
 import { getElementClasses } from "./element-identification";
+import { getPrototypeScreenshotRoot } from "@prototype/lib/tool-portal";
 
 export const PROTOTYPE_TARGET_ATTR = "data-prototype-target";
 const PROTOTYPE_SCREENSHOT_ROOT = "[data-prototype-screenshot]";
@@ -37,9 +38,17 @@ export function getCommentsSidebarWidth(): number {
 }
 
 export function getCommentsSidebarInset(): number {
-  if (!document.documentElement.hasAttribute("data-comments-sidebar-open")) return 0;
-  // Inline sidebar already shrinks the prototype content area — no coordinate offset needed.
-  if (document.documentElement.hasAttribute("data-comments-sidebar-inline")) return 0;
+  const isOpen =
+    document.documentElement.hasAttribute("data-comments-sidebar-open") ||
+    document.documentElement.hasAttribute("data-prototype-review-sidebar-open");
+  if (!isOpen) return 0;
+
+  const isInline =
+    document.documentElement.hasAttribute("data-comments-sidebar-inline") ||
+    document.documentElement.hasAttribute("data-prototype-review-sidebar-inline") ||
+    getPrototypeScreenshotRoot() != null;
+  if (isInline) return 0;
+
   return getCommentsSidebarWidth();
 }
 

package/src/lib/prototype-comments/core/comment-capture-blocked.ts

@@ -1,4 +1,5 @@
 import { closestCrossingShadow } from "./element-identification";
+import { buildSidebarInteractivePointerCss } from "@prototype/lib/platform-ui/sidebar-interactive-cursor";
 
 /** DOM regions where comment capture must not attach (plugin chrome, not prototype UI). */
 export const COMMENT_CAPTURE_BLOCKED_SELECTORS = [
@@ -21,6 +22,28 @@ export function isCommentCaptureBlockedTarget(target: HTMLElement): boolean {
   );
 }
 
+/** Plugin chrome where interacting should exit comment mode (not the prototype canvas). */
+export const COMMENT_MODE_CHROME_SELECTORS = [
+  "[data-prototype-review-trigger]",
+  "[data-prototype-review-sidebar]",
+  "[data-prototype-review-panel]",
+  "[data-feedback-toolbar]",
+  "[data-comment-capture-toolbar]",
+  "[data-comments-sidebar]",
+  "#prototype-comments-sidebar-root",
+] as const;
+
+export const COMMENT_MODE_TOGGLE_SELECTOR = "[data-prototype-comment-mode-toggle]";
+
+export function isCommentModeChromeInteraction(target: HTMLElement): boolean {
+  if (closestCrossingShadow(target, COMMENT_MODE_TOGGLE_SELECTOR) != null) {
+    return false;
+  }
+  return COMMENT_MODE_CHROME_SELECTORS.some(
+    (selector) => closestCrossingShadow(target, selector) != null,
+  );
+}
+
 /** CSS :not() chain for descendants that should not receive comment-mode crosshair. */
 export function buildCommentCaptureCursorExclusionCss(): string {
   return COMMENT_CAPTURE_BLOCKED_SELECTORS.flatMap((selector) => [
@@ -43,5 +66,6 @@ export function buildCommentCaptureCursorStyles(): string {
     ${blockedCursorReset} {
       cursor: auto !important;
     }
+    ${buildSidebarInteractivePointerCss({ important: true })}
   `;
 }