proto-plugin 0.1.0

package/src/config/create-prototype-gallery-page.tsx

@@ -0,0 +1,65 @@
+import "server-only";
+
+import { PrototypeGalleryClient } from "@prototype/components/prototype-gallery-client";
+import { PrototypeGalleryHeader } from "@prototype/components/shell/prototype-gallery-shell";
+import { createPrototypeRegistry } from "@prototype/lib/prototypes/create-prototype-registry";
+import type { PrototypeConfig } from "@prototype/lib/prototypes/prototype-config-types";
+
+import { readScreenshotManifest } from "../lib/prototypes/screenshot-manifest";
+
+type PrototypeGalleryPageOptions = {
+  title?: string;
+  description?: string;
+  eyebrow?: string;
+};
+
+export function createPrototypeGalleryPage(
+  config: PrototypeConfig,
+  options: PrototypeGalleryPageOptions = {},
+) {
+  const registry = createPrototypeRegistry(config);
+  const {
+    title = "Prototypes",
+    description = "UI experiments and concept explorations. Select a prototype to open it.",
+    eyebrow,
+  } = options;
+
+  async function PrototypeGallery() {
+    const prototypes = registry.getAllPrototypes();
+    const screenshotVersions =
+      process.env.NODE_ENV === "development"
+        ? await readScreenshotManifest()
+        : {};
+
+    if (prototypes.length === 0) {
+      return (
+        <p className="text-muted-foreground py-12 text-sm">
+          No prototypes yet. Add one in{" "}
+          <code className="text-foreground">prototype.config.ts</code>.
+        </p>
+      );
+    }
+
+    return (
+      <PrototypeGalleryClient
+        prototypes={prototypes}
+        screenshotVersions={screenshotVersions}
+      />
+    );
+  }
+
+  function HomePage() {
+    return (
+      <div className="px-10 lg:px-16">
+        <PrototypeGalleryHeader
+          eyebrow={eyebrow}
+          title={title}
+          description={description}
+        />
+        <PrototypeGallery />
+      </div>
+    );
+  }
+
+  return HomePage;
+}

package/src/config/create-prototype-host-app.tsx

@@ -0,0 +1,121 @@
+import "server-only";
+
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+
+import { PrototypeShell } from "@prototype/components/shell/prototype-shell";
+import { PrototypeDefaultStateMapPage } from "@prototype/components/prototypes/prototype-default-state-map-page";
+import { createPrototypeRegistry } from "@prototype/lib/prototypes/create-prototype-registry";
+import type {
+  PrototypeConfig,
+  PrototypeExtraRoute,
+} from "@prototype/lib/prototypes/prototype-config-types";
+
+import { createPrototypePage } from "./create-prototype-page";
+
+function matchExtraRoute(
+  path: string[],
+  pattern: string[],
+  params: Record<string, string>,
+): boolean {
+  if (path.length !== pattern.length) return false;
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const segment = pattern[index]!;
+    const value = path[index]!;
+
+    if (segment.startsWith("[") && segment.endsWith("]")) {
+      params[segment.slice(1, -1)] = value;
+      continue;
+    }
+
+    if (segment !== value) return false;
+  }
+
+  return true;
+}
+
+function findExtraRoute(
+  path: string[],
+  routes: PrototypeExtraRoute[] | undefined,
+): { route: PrototypeExtraRoute; params: Record<string, string> } | null {
+  for (const route of routes ?? []) {
+    const params: Record<string, string> = {};
+    if (matchExtraRoute(path, route.segments, params)) {
+      return { route, params };
+    }
+  }
+  return null;
+}
+
+export function createPrototypeCatchAllPage(config: PrototypeConfig) {
+  const registry = createPrototypeRegistry(config);
+  const prototypePage = createPrototypePage(config);
+
+  function generateStaticParams() {
+    const prototypePaths = prototypePage.generateStaticParams().map(({ slug }) => ({
+      path: ["prototypes", slug],
+    }));
+    const stateMapPaths = registry.getAllPrototypes().map(({ slug }) => ({
+      path: ["prototypes", slug, "states"],
+    }));
+
+    return [...prototypePaths, ...stateMapPaths];
+  }
+
+  async function CatchAllPage({
+    params,
+  }: {
+    params: Promise<{ path?: string[] }>;
+  }) {
+    const { path = [] } = await params;
+
+    if (path.length === 2 && path[0] === "prototypes") {
+      const slug = path[1]!;
+      return prototypePage.default({ params: Promise.resolve({ slug }) });
+    }
+
+    const extra = findExtraRoute(path, config.extraRoutes);
+    if (extra) {
+      const { route, params: routeParams } = extra;
+      const Component = route.component;
+
+      if (route.shellSlug && route.componentRegistry) {
+        return (
+          <Suspense fallback={null}>
+            <PrototypeShell
+              slug={route.shellSlug}
+              componentRegistry={route.componentRegistry}
+            >
+              <Component {...routeParams} />
+            </PrototypeShell>
+          </Suspense>
+        );
+      }
+
+      return <Component {...routeParams} />;
+    }
+
+    if (path.length === 3 && path[0] === "prototypes" && path[2] === "states") {
+      const slug = path[1]!;
+      const prototype = registry.getPrototype(slug);
+      const componentRegistry = registry.getPrototypeComponentRegistryForSlug(slug);
+
+      if (!prototype) {
+        notFound();
+      }
+
+      return (
+        <Suspense fallback={null}>
+          <PrototypeShell slug={slug} componentRegistry={componentRegistry}>
+            <PrototypeDefaultStateMapPage slug={slug} />
+          </PrototypeShell>
+        </Suspense>
+      );
+    }
+
+    notFound();
+  }
+
+  return { default: CatchAllPage, generateStaticParams };
+}

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

@@ -0,0 +1,41 @@
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+
+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 PrototypePageProps = {
+  params: Promise<{ slug: string }>;
+};
+
+export function createPrototypePage(config: PrototypeConfig) {
+  const registry = createPrototypeRegistry(config);
+
+  function generateStaticParams() {
+    return registry.getAllPrototypes().map((prototype) => ({
+      slug: prototype.slug,
+    }));
+  }
+
+  async function PrototypePage({ params }: PrototypePageProps) {
+    const { slug } = await params;
+    const prototype = registry.getPrototype(slug);
+    const Component = registry.getPrototypeComponent(slug);
+    const componentRegistry = registry.getPrototypeComponentRegistryForSlug(slug);
+
+    if (!prototype || !Component) {
+      notFound();
+    }
+
+    return (
+      <Suspense fallback={null}>
+        <PrototypeShell slug={slug} componentRegistry={componentRegistry}>
+          <Component />
+        </PrototypeShell>
+      </Suspense>
+    );
+  }
+
+  return { default: PrototypePage, generateStaticParams };
+}

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

@@ -0,0 +1,28 @@
+import type { ComponentType, ReactNode } from "react";
+
+import { PrototypeGalleryShell } from "@prototype/components/shell/prototype-gallery-shell";
+
+import { PrototypeSiteLayoutClient } from "./prototype-site-layout-client";
+
+type PrototypeSiteLayoutOptions = {
+  toaster?: ReactNode;
+};
+
+export function createPrototypeSiteLayout(
+  options: PrototypeSiteLayoutOptions = {},
+) {
+  return function PrototypeSiteLayout({
+    children,
+  }: Readonly<{
+    children: ReactNode;
+  }>) {
+    return (
+      <PrototypeSiteLayoutClient
+        galleryShell={PrototypeGalleryShell as ComponentType<{ children: ReactNode }>}
+        toaster={options.toaster}
+      >
+        {children}
+      </PrototypeSiteLayoutClient>
+    );
+  };
+}

package/src/config/define-prototype-config.ts

@@ -0,0 +1,7 @@
+import type { PrototypeConfig } from "@prototype/lib/prototypes/prototype-config-types";
+import { setPrototypeConfig } from "@prototype/lib/prototypes/create-prototype-registry";
+
+export function definePrototypeConfig(config: PrototypeConfig): PrototypeConfig {
+  setPrototypeConfig(config);
+  return config;
+}

package/src/config/prototype-icon.tsx

@@ -0,0 +1,25 @@
+import { ImageResponse } from "next/og";
+
+export const size = { width: 32, height: 32 };
+export const contentType = "image/png";
+
+export default function PrototypeIcon() {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 28,
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          lineHeight: 1,
+        }}
+      >
+        🎨
+      </div>
+    ),
+    { ...size },
+  );
+}

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

@@ -0,0 +1,35 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import type { ComponentType, ReactNode } from "react";
+
+type PrototypeSiteLayoutClientProps = {
+  children: ReactNode;
+  galleryShell: ComponentType<{ children: ReactNode }>;
+  toaster: ReactNode;
+};
+
+export function PrototypeSiteLayoutClient({
+  children,
+  galleryShell: GalleryShell,
+  toaster,
+}: PrototypeSiteLayoutClientProps) {
+  const pathname = usePathname();
+  const isGalleryHome = pathname === "/";
+
+  if (isGalleryHome) {
+    return (
+      <>
+        <GalleryShell>{children}</GalleryShell>
+        {toaster}
+      </>
+    );
+  }
+
+  return (
+    <div className="bg-[var(--bg-ground)] flex h-svh overflow-hidden">
+      {children}
+      {toaster}
+    </div>
+  );
+}

package/src/config/with-prototype.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from "next";
+
+export type WithPrototypeOptions = {
+  configPath?: string;
+  nextConfig?: NextConfig;
+};
+
+export function withPrototype(
+  options: WithPrototypeOptions = {},
+): NextConfig {
+  const { nextConfig = {} } = options;
+
+  return {
+    ...nextConfig,
+    transpilePackages: [
+      ...(nextConfig.transpilePackages ?? []),
+      "proto-plugin",
+    ],
+  };
+}

package/src/index.ts

@@ -0,0 +1,303 @@
+export { definePrototypeConfig } from "./config/define-prototype-config";
+export { createPrototypePage } from "./config/create-prototype-page";
+export { createPrototypeSiteLayout } from "./config/create-prototype-site-layout";
+export { withPrototype } from "./config/with-prototype";
+
+export {
+  createPrototypeRegistry,
+  getAllPrototypes,
+  getPrototype,
+  getPrototypeComponent,
+  getPrototypeComponentRegistryForSlug,
+  setPrototypeConfig,
+} from "./lib/prototypes/create-prototype-registry";
+
+export type {
+  PrototypeConfig,
+  PrototypeDefinition,
+  PrototypeExtraRoute,
+  PrototypeMetadata,
+} from "./lib/prototypes/prototype-config-types";
+
+export {
+  PrototypeComponent,
+  PrototypeTarget,
+  PrototypeTargetIdProvider,
+  usePrototypeSlug,
+  buildPrototypeTargetId,
+} from "./components/prototypes/prototype-target";
+
+export {
+  PrototypeControl,
+  PrototypeControlGroup,
+} from "./components/prototypes/prototype-control";
+
+export { PrototypeShell } from "./components/shell/prototype-shell";
+
+export { PrototypeProvider } from "./components/prototype-provider";
+
+export { PrototypeVariantExplorer } from "./components/prototypes/prototype-variant-explorer";
+
+export { PrototypeVercelPreviewModal } from "./components/prototypes/prototype-vercel-preview-modal";
+export type { PrototypeVercelPreviewModalProps } from "./components/prototypes/prototype-vercel-preview-modal";
+
+export { PrototypeTweaks } from "./components/prototypes/prototype-tweaks";
+export type { PrototypeTweakConfig } from "./components/prototypes/prototype-tweaks";
+
+export { usePrototypeComments } from "./lib/prototypes/use-prototype-comments";
+
+export {
+  usePersistPrototypeLiveState,
+  readPersistedPrototypeLiveState,
+} from "./lib/prototypes/use-persisted-local-state";
+
+export type { DesignExplorationConfig } from "./lib/prototypes/design-exploration-types";
+
+export {
+  buildCreateDesignExplorationCopyText,
+  buildCreateDesignExplorationPrompt,
+  buildResetBriefDefaultsPrompt,
+  getAdjacentDesignExplorationVariant,
+} from "./lib/prototypes/design-exploration-types";
+
+export {
+  buildCreatePreviewStateCopyText,
+  buildCreatePreviewStatePrompt,
+} from "./lib/prototypes/prototype-preview-state-types";
+export type { PrototypePreviewState } from "./lib/prototypes/prototype-preview-state-types";
+
+export {
+  buildAddReferenceDocCopyText,
+  buildAddReferenceDocPrompt,
+  defaultReferenceDocsConfigPath,
+  isValidReferenceDoc,
+  isValidReferenceDocInput,
+  normalizeReferenceDocLink,
+} from "./lib/prototypes/reference-docs";
+export type { PrototypeReferenceDoc } from "./lib/prototypes/reference-docs";
+export { useRegisterPrototypeReferenceDocs } from "./lib/prototypes/use-register-prototype-reference-docs";
+export {
+  buildPreviewStateCanvasEdges,
+  buildPreviewStateCanvasLayout,
+  buildPreviewStateCanvasNodes,
+  buildPreviewStatePickerOptions,
+  definePreviewStateRegistry,
+  flattenPreviewStateLabels,
+  getPreviewStateNodeHeight,
+  normalizePreviewStateCanvasRowStates,
+} from "./lib/prototypes/prototype-preview-state-registry";
+export type {
+  DefinedPreviewStateRegistry,
+  PreviewStateCanvasLayout,
+  PreviewStateCanvasRowPlacement,
+  PreviewStateCanvasRowStatePlacement,
+  PrototypePreviewStateCanvasLayoutSpec,
+  PrototypePreviewStateDefinition,
+  PrototypePreviewStateEdge,
+  PrototypePreviewStateRegistry,
+  PrototypePreviewStateVariant,
+  ResolvedPrototypePreviewStateDefinition,
+} from "./lib/prototypes/prototype-preview-state-registry";
+export {
+  getStateCanvasNodeHeight,
+  PROTOTYPE_STATE_CANVAS_PADDING,
+  PROTOTYPE_STATE_NODE_COLUMN_GAP,
+  PROTOTYPE_STATE_NODE_ROW_GAP,
+  PROTOTYPE_STATE_SECTION_TO_NODES,
+  stateCanvasColumnX,
+} from "./lib/prototypes/prototype-state-canvas-constants";
+
+export { PrototypeGalleryClient } from "./components/prototype-gallery-client";
+
+export {
+  PrototypeGalleryShell,
+  PrototypeGalleryHeader,
+  PrototypeGalleryPage,
+} from "./components/shell/prototype-gallery-shell";
+
+export { screenshotSrc } from "./lib/prototypes/screenshot-src";
+
+export {
+  definePrototypeComponentRegistry,
+  type PrototypeComponentRegistry,
+} from "./lib/prototypes/prototype-component-registry";
+
+export { PrototypeControls } from "./components/prototypes/prototype-controls";
+
+export {
+  PrototypeStateCanvasRegistrar,
+  PrototypeStateCanvasView,
+  buildStateMapHref,
+  getDefaultPrototypeStateMapPath,
+  parseStateMapReturnTo,
+  PROTOTYPE_STATE_MAP_RETURN_TO_PARAM,
+  type PrototypeStateCanvasConfig,
+  type PrototypeStateCanvasEdge,
+  type PrototypeStateCanvasNode,
+  type PrototypeStateCanvasNodeCallout,
+  type PrototypeStateCanvasSection,
+  type PrototypeStateMapAnnotationEntry,
+  buildStateMapAnnotationEntries,
+  stateMapHasAnnotations,
+} from "./components/prototypes/prototype-state-canvas";
+
+export { PrototypeStateScreenshotCapture } from "./components/shell/prototype-state-screenshot-capture";
+
+export { PrototypeStateScreenshotPreview } from "./components/prototypes/prototype-state-screenshot-preview";
+
+export {
+  sanitizeStateIdForFilename,
+  stateScreenshotManifestKey,
+  stateScreenshotPublicPath,
+  stateScreenshotSrc,
+} from "./lib/prototypes/prototype-state-screenshot";
+
+export {
+  StateMapHighlightProvider,
+  StateMapHighlightRegion,
+  StateMapPreviewHighlightOverlay,
+  useStateMapHighlight,
+} from "./components/prototypes/state-map-wireframe-highlight";
+
+export {
+  parseStateMapAnnotation,
+  resolveBulletHighlightId,
+  stateMapAnnotationHasInteractiveBullets,
+} from "./lib/prototypes/state-map-annotation";
+export type {
+  ParsedStateMapAnnotation,
+  ParsedStateMapBullet,
+} from "./lib/prototypes/state-map-annotation";
+
+export type { StateMapHighlightRect } from "./lib/prototypes/prototype-state-canvas-types";
+
+export { PrototypeReviewDropdownMenuItem } from "./components/prototypes/prototype-review-dropdown-menu-item";
+
+export { PrototypeReviewDropdownMenuSeparator } from "./components/prototypes/prototype-review-dropdown-menu-separator";
+
+export { PrototypeReviewPanelSelect } from "./components/prototypes/prototype-review-panel-select";
+
+export {
+  ControlsPanelOption,
+  ControlsPanelOptionGroup,
+  ControlsPanelOptionSeparator,
+} from "./components/platform-ui/controls-panel-options";
+
+export {
+  ControlsPanelSelect,
+} from "./components/platform-ui/controls-panel-select";
+export type {
+  ControlsPanelSelectEntry,
+  ControlsPanelSelectOption,
+  ControlsPanelSelectSeparator,
+  ControlsPanelSelectSubmenu,
+  ControlsPanelSelectSubmenuOption,
+} from "./components/platform-ui/controls-panel-select";
+
+export { PrototypeReviewPanelMenuItem } from "./components/prototypes/prototype-review-panel-menu-item";
+
+export { PrototypeReviewPanelMenuSeparator } from "./components/prototypes/prototype-review-panel-menu-separator";
+
+export {
+  usePrototypeReview,
+  usePrototypeReviewOptional,
+} from "./lib/prototypes/prototype-review-context";
+export type {
+  PrototypeReviewSidebarPanel,
+  PrototypeVariantSet,
+  PrototypeViewportLayout,
+} from "./lib/prototypes/prototype-review-context";
+
+export {
+  PROTOTYPE_MOBILE_VIEWPORT_HEIGHT_PX,
+  PROTOTYPE_MOBILE_VIEWPORT_WIDTH_PX,
+} from "./lib/prototypes/prototype-review-context";
+export {
+  VariantSetLucideIcon,
+  resolveVariantSetLucideIcon,
+} from "./lib/prototypes/variant-set-lucide-icon";
+export { usePrototypeViewportFrame } from "./lib/prototypes/use-prototype-viewport-frame";
+export { usePrototypeMobileViewportFrame } from "./lib/prototypes/use-prototype-mobile-viewport-frame";
+
+export {
+  PROTOTYPE_CHROME_ROOT_ID,
+  PROTOTYPE_COMMENTS_SIDEBAR_ROOT_ID,
+  PROTOTYPE_PREVIEW_STAGE_ID,
+  PROTOTYPE_ROOT_ID,
+  PROTOTYPE_SCREENSHOT_ATTR,
+  PROTOTYPE_VIEWPORT_ID,
+  getPrototypeChromeRoot,
+  getPrototypePreviewStage,
+  getPrototypeScreenshotRoot,
+} from "./lib/tool-portal";
+
+export {
+  prototypeChangelogMetaRedisKey,
+  isValidChangelogMeta,
+  parseChangelogMeta,
+  normalizeChangelogMetaPayload,
+  EMPTY_CHANGELOG_META,
+} from "./lib/prototypes/changelog-meta";
+export type { PrototypeChangelogMeta } from "./lib/prototypes/changelog-meta";
+export { createChangelogMetaStorageAdapter } from "./lib/prototypes/changelog-meta-storage";
+export {
+  ChangelogMetaProvider,
+  useChangelogMeta,
+  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,
+  getCommentRootAnnotations,
+  isChangelogAnnotation,
+} from "./lib/prototype-comments/core/annotation-channel";
+export type { AnnotationChannel } from "./lib/prototype-comments/core/annotation-channel";
+
+export { isValidAnnotation } from "./lib/prototype-comments/core/validation";
+export {
+  isAnnotationDeleted,
+  isVisibleAnnotation,
+} from "./lib/prototype-comments/core/annotation-status";
+export type { CommentAnnotationFields } from "./lib/prototype-comments/core/types";
+
+export { PrototypeSpecPanelContent } from "./components/prototypes/prototype-spec-panel-content";
+export type { PrototypeSpecPanelContentProps } from "./components/prototypes/prototype-spec-panel-content";
+
+export {
+  PR_TARGET_HIGHLIGHT_BORDER,
+  PR_TARGET_HIGHLIGHT_FILL,
+} 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 type {
+  PrSplitEntry,
+  PrSplitEntrySize,
+  PrSplitConfig,
+  PrSplitAgentPromptConfig,
+  PrSplitUrlConfig,
+} from "./lib/pr-split/pr-split-types";
+
+export { resolveSourcePreviewUrl } from "./lib/pr-split/resolve-source-preview-url";
+export { usePrVercelPreviews } from "./lib/pr-split/use-pr-vercel-previews";
+
+export {
+  buildVercelPreviewPageUrl,
+  parseGithubPrUrl,
+  parseVercelGithubCommentBody,
+} from "./lib/vercel-preview/parse-vercel-github-comment";
+export type {
+  VercelPreviewFromPr,
+  VercelPreviewProject,
+} from "./lib/vercel-preview/parse-vercel-github-comment";