proto-plugin 0.1.0

package/src/lib/prototypes/design-exploration-types.ts

@@ -0,0 +1,203 @@
+import type { ReactNode } from "react";
+
+export type DesignExplorationVariantOption<TVariant extends string> = {
+  value: TVariant;
+  label: string;
+  hint?: string;
+};
+
+export type DesignExplorationRationale = {
+  good: string;
+  bad: string;
+};
+
+export type DesignExplorationBrief = {
+  titleDefault: string;
+  descriptionDefault: string;
+};
+
+/** Open-ended context — prototype defines the JSON shape. */
+export type DesignExplorationContext = {
+  label: string;
+  data: unknown;
+  render?: (data: unknown) => ReactNode;
+  defaultExpanded?: boolean;
+  /** Stable id suffix for aria-controls on the collapsible panel. */
+  panelId?: string;
+};
+
+export type MobbinReference = {
+  id: string;
+  appName: string;
+  imageUrl: string;
+  mobbinUrl: string;
+  relevance: string;
+  variantHint?: string;
+};
+
+export type DesignExplorationMobbin = {
+  references: MobbinReference[];
+  title?: string;
+  description?: string;
+  imagePathForReference?: (id: string) => string;
+};
+
+export type DesignExplorationVariantsSection = {
+  title?: string;
+  description?: string;
+};
+
+/** Persists to KV via `storageKeyPrefix` — use `useDesignExplorationDefault`. */
+export type DesignExplorationConfig<TVariant extends string> = {
+  componentIdPrefix: string;
+  variantTabsIdPrefix: string;
+  storageKeyPrefix: string;
+  variant: TVariant;
+  onVariantChange: (variant: TVariant) => void;
+  options: DesignExplorationVariantOption<TVariant>[];
+  rationale: Record<TVariant, DesignExplorationRationale>;
+  renderers: Record<TVariant, () => ReactNode>;
+  brief: DesignExplorationBrief;
+  context?: DesignExplorationContext;
+  mobbin?: DesignExplorationMobbin;
+  variantsSection?: DesignExplorationVariantsSection;
+  /** Label for prev/next variant tab buttons. Default: "variant". */
+  variantTabAriaLabel?: string;
+  /** Path to design exploration config — included in reset-brief copy prompt. */
+  briefConfigFilePath?: string;
+};
+
+/** Plain-text copy of the overview fields as shown in the design brief modal. */
+export function buildBriefOverviewCopyText(
+  title: string,
+  description: string,
+): string {
+  const trimmedTitle = title.trim();
+  const trimmedDescription = description.trim();
+  if (!trimmedTitle) return trimmedDescription;
+  if (!trimmedDescription) return trimmedTitle;
+  return `${trimmedTitle}\n\n${trimmedDescription}`;
+}
+
+export function buildCreateDesignExplorationPrompt({
+  slug,
+  existingExplorations = [],
+  origin = "http://localhost:3003",
+  briefText,
+}: {
+  slug: string;
+  existingExplorations?: Array<{ id: string; label: string }>;
+  origin?: string;
+  briefText?: string;
+}): string {
+  const prototypeUrl = `${origin}/prototypes/${slug}`;
+  const variantSetsRegistrar = `src/prototypes/${slug}/_components/*-variant-sets.tsx`;
+  const trimmedBrief = briefText?.trim() ?? "";
+
+  const lines = [
+    `Add a new design exploration to the "${slug}" prototype.`,
+    "",
+    "## Brief",
+  ];
+
+  if (trimmedBrief) {
+    lines.push(trimmedBrief);
+  } else {
+    lines.push(
+      "Describe the UI problem to explore and the 2+ directions to compare:",
+      "- Problem:",
+      "- Variants to explore:",
+    );
+  }
+
+  if (existingExplorations.length > 0) {
+    lines.push("", "## Existing explorations on this prototype");
+    for (const exploration of existingExplorations) {
+      lines.push(`- ${exploration.label} (\`${exploration.id}\`)`);
+    }
+  }
+
+  lines.push(
+    "",
+    "## Prototype",
+    `- Slug: \`${slug}\``,
+    `- Preview: ${prototypeUrl}`,
+    "",
+    "## Instructions",
+    "Follow AGENTS.md → Design exploration. Do not register a new prototype slug — add a design exploration variant set on this page.",
+    "",
+    "1. Add `{ id, label, previewMode? }` to the variant sets registrar (e.g. `" +
+      variantSetsRegistrar +
+      "`).",
+    "2. Create `*-design-exploration-config.tsx` with options, rationale, renderers, and brief defaults.",
+    "3. Create `*-variant-toggle.tsx` mounting `PrototypeVariantExplorer` with matching `variantSet={{ id, label }}`.",
+    "4. Register static ids + any `dynamicPrefixes` in `src/prototypes/" +
+      slug +
+      "/component-ids.ts`.",
+    "5. If the exploration needs a specific page state, wire preview mode in mock data / URL params and render the toggle on the page.",
+    "6. Prepend new variant options to the top of `*_VARIANT_OPTIONS` so newest explorations appear first.",
+    "7. Run `pnpm verify:prototype-ids`.",
+    "",
+    "Reference: `src/prototypes/example-feature/_components/no-data-design-exploration-config.tsx` + `no-data-variant-toggle.tsx`.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildCreateDesignExplorationCopyText({
+  slug,
+  existingExplorations = [],
+  origin = "http://localhost:3003",
+  briefText,
+}: {
+  slug: string;
+  existingExplorations?: Array<{ id: string; label: string }>;
+  origin?: string;
+  briefText: string;
+}): string {
+  const trimmedBrief = briefText.trim();
+  const prompt = buildCreateDesignExplorationPrompt({
+    slug,
+    existingExplorations,
+    origin,
+    briefText: trimmedBrief,
+  });
+
+  return `${trimmedBrief}\n\n---\n\n${prompt}`;
+}
+
+export function buildResetBriefDefaultsPrompt({
+  brief,
+  configFilePath,
+}: {
+  brief: DesignExplorationBrief;
+  configFilePath?: string;
+}): string {
+  const target = configFilePath ?? "the design exploration config file";
+
+  return [
+    "Update the design exploration overview defaults.",
+    "",
+    `In ${target}, set brief.titleDefault and brief.descriptionDefault to:`,
+    "",
+    `Title: ${brief.titleDefault}`,
+    "",
+    "Description:",
+    brief.descriptionDefault,
+  ].join("\n");
+}
+
+/**
+ * Prepend new entries to the top of *_VARIANT_OPTIONS so they appear first in the
+ * design-brief scroll view (see AGENTS.md). Default variant is stored in KV.
+ */
+export function getAdjacentDesignExplorationVariant<TVariant extends string>(
+  options: DesignExplorationVariantOption<TVariant>[],
+  current: TVariant,
+  direction: "prev" | "next",
+): TVariant {
+  const index = options.findIndex((option) => option.value === current);
+  const offset = direction === "prev" ? -1 : 1;
+  const nextIndex = (index + offset + options.length) % options.length;
+  return options[nextIndex].value;
+}

package/src/lib/prototypes/prototype-comment-registry.tsx

@@ -0,0 +1,145 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+
+import type { AnnotationTargetOptions } from "@prototype/lib/prototype-comments/core/annotation-target";
+
+import {
+  augmentLiveStateWithReviewState,
+  restoreLiveStateWithReviewState,
+  type PrototypeCommentReviewStateBridge,
+} from "./prototype-comment-review-state";
+
+export type PrototypeCommentHandlers = {
+  getLiveState: () => unknown;
+  onRestore: (live: unknown) => void;
+  resolveTargetOptions?: () => AnnotationTargetOptions;
+};
+
+type PrototypeCommentRegistryValue = {
+  register: (handlers: PrototypeCommentHandlers) => void;
+  unregister: (handlers: PrototypeCommentHandlers) => void;
+  registerReviewStateBridge: (
+    bridge: PrototypeCommentReviewStateBridge | null,
+  ) => void;
+  readHandlers: () => PrototypeCommentHandlers | null;
+  /** Notify subscribers that the prototype's live state changed. */
+  notifyLiveStateChange: () => void;
+  /** Subscribe to live-state changes. Returns an unsubscribe function. */
+  subscribeLiveStateChange: (listener: () => void) => () => void;
+};
+
+const PrototypeCommentRegistryContext =
+  createContext<PrototypeCommentRegistryValue | null>(null);
+
+export function PrototypeCommentRegistryProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const handlersRef = useRef<PrototypeCommentHandlers | null>(null);
+  const reviewBridgeRef = useRef<PrototypeCommentReviewStateBridge | null>(
+    null,
+  );
+  const liveStateListenersRef = useRef<Set<() => void>>(new Set());
+
+  const notifyLiveStateChange = useCallback(() => {
+    liveStateListenersRef.current.forEach((listener) => listener());
+  }, []);
+
+  const subscribeLiveStateChange = useCallback((listener: () => void) => {
+    liveStateListenersRef.current.add(listener);
+    return () => {
+      liveStateListenersRef.current.delete(listener);
+    };
+  }, []);
+
+  const register = useCallback((handlers: PrototypeCommentHandlers) => {
+    handlersRef.current = handlers;
+  }, []);
+
+  const unregister = useCallback((handlers: PrototypeCommentHandlers) => {
+    if (handlersRef.current === handlers) {
+      handlersRef.current = null;
+    }
+  }, []);
+
+  const registerReviewStateBridge = useCallback(
+    (bridge: PrototypeCommentReviewStateBridge | null) => {
+      reviewBridgeRef.current = bridge;
+    },
+    [],
+  );
+
+  const readHandlers = useCallback((): PrototypeCommentHandlers | null => {
+    const prototypeHandlers = handlersRef.current;
+    if (!prototypeHandlers) return null;
+
+    const bridge = reviewBridgeRef.current;
+    if (!bridge?.prodReferenceAvailable) {
+      return prototypeHandlers;
+    }
+
+    return {
+      getLiveState: () =>
+        augmentLiveStateWithReviewState(
+          prototypeHandlers.getLiveState(),
+          bridge.getShowProdReference(),
+        ),
+      onRestore: (live) => {
+        restoreLiveStateWithReviewState(
+          live,
+          prototypeHandlers.onRestore,
+          bridge,
+        );
+      },
+      ...(prototypeHandlers.resolveTargetOptions
+        ? {
+            resolveTargetOptions: prototypeHandlers.resolveTargetOptions,
+          }
+        : {}),
+    };
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      register,
+      unregister,
+      registerReviewStateBridge,
+      readHandlers,
+      notifyLiveStateChange,
+      subscribeLiveStateChange,
+    }),
+    [
+      register,
+      unregister,
+      registerReviewStateBridge,
+      readHandlers,
+      notifyLiveStateChange,
+      subscribeLiveStateChange,
+    ],
+  );
+
+  return (
+    <PrototypeCommentRegistryContext.Provider value={value}>
+      {children}
+    </PrototypeCommentRegistryContext.Provider>
+  );
+}
+
+export function usePrototypeCommentRegistry(): PrototypeCommentRegistryValue {
+  const context = useContext(PrototypeCommentRegistryContext);
+  if (!context) {
+    throw new Error(
+      "usePrototypeCommentRegistry must be used within PrototypeCommentRegistryProvider",
+    );
+  }
+  return context;
+}

package/src/lib/prototypes/prototype-comment-review-bridge.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { useLayoutEffect, useRef } from "react";
+
+import { usePrototypeReviewOptional } from "./prototype-review-context";
+import { usePrototypeCommentRegistry } from "./prototype-comment-registry";
+import type { PrototypeCommentReviewStateBridge } from "./prototype-comment-review-state";
+
+/** Registers prod-reference toggle state with the comment capture/restore pipeline. */
+export function PrototypeCommentReviewBridge() {
+  const review = usePrototypeReviewOptional();
+  const { registerReviewStateBridge } = usePrototypeCommentRegistry();
+  const reviewRef = useRef(review);
+  reviewRef.current = review;
+
+  useLayoutEffect(() => {
+    const currentReview = reviewRef.current;
+    if (!currentReview?.prodReferenceAvailable) {
+      registerReviewStateBridge(null);
+      return;
+    }
+
+    const bridge: PrototypeCommentReviewStateBridge = {
+      prodReferenceAvailable: true,
+      getShowProdReference: () => reviewRef.current?.showProdReference ?? false,
+      setShowProdReference: (show) => {
+        reviewRef.current?.setShowProdReference(show);
+      },
+    };
+
+    registerReviewStateBridge(bridge);
+    return () => registerReviewStateBridge(null);
+  }, [
+    registerReviewStateBridge,
+    review?.prodReferenceAvailable,
+    review?.setShowProdReference,
+  ]);
+
+  return null;
+}

package/src/lib/prototypes/prototype-comment-review-state.ts

@@ -0,0 +1,57 @@
+export const COMMENT_SHOW_PROD_REFERENCE_KEY = "showProdReference";
+
+export type PrototypeCommentReviewStateBridge = {
+  prodReferenceAvailable: boolean;
+  getShowProdReference: () => boolean;
+  setShowProdReference: (show: boolean) => void;
+};
+
+export function augmentLiveStateWithReviewState(
+  live: unknown,
+  showProdReference: boolean,
+): Record<string, unknown> {
+  return {
+    ...(typeof live === "object" && live !== null
+      ? (live as Record<string, unknown>)
+      : {}),
+    [COMMENT_SHOW_PROD_REFERENCE_KEY]: showProdReference,
+  };
+}
+
+function splitPrototypeLiveState(live: unknown): {
+  showProdReference: boolean;
+  prototypeLive: unknown;
+} {
+  if (typeof live !== "object" || live === null) {
+    return { showProdReference: false, prototypeLive: live };
+  }
+
+  const state = live as Record<string, unknown>;
+  const showProdReference = state[COMMENT_SHOW_PROD_REFERENCE_KEY] === true;
+  const { [COMMENT_SHOW_PROD_REFERENCE_KEY]: _removed, ...prototypeLive } =
+    state;
+
+  return { showProdReference, prototypeLive };
+}
+
+export function restoreLiveStateWithReviewState(
+  live: unknown,
+  onRestorePrototypeLive: (live: unknown) => void,
+  bridge: PrototypeCommentReviewStateBridge | null,
+): void {
+  const { showProdReference, prototypeLive } = splitPrototypeLiveState(live);
+
+  if (!bridge?.prodReferenceAvailable) {
+    onRestorePrototypeLive(prototypeLive);
+    return;
+  }
+
+  if (showProdReference) {
+    onRestorePrototypeLive(prototypeLive);
+    bridge.setShowProdReference(true);
+    return;
+  }
+
+  bridge.setShowProdReference(false);
+  onRestorePrototypeLive(prototypeLive);
+}

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

@@ -0,0 +1,40 @@
+export type PrototypeComponentRegistry = {
+  /** Static segment ids (slug is prefixed at runtime). */
+  ids: readonly string[];
+  /** Allowed dynamic id prefixes, e.g. `mock-table.row.` */
+  dynamicPrefixes?: readonly string[];
+};
+
+const registries: Record<string, PrototypeComponentRegistry> = {};
+
+export function registerPrototypeComponentRegistry(
+  slug: string,
+  registry: PrototypeComponentRegistry,
+) {
+  registries[slug] = registry;
+}
+
+export function getPrototypeComponentRegistry(
+  slug: string,
+): PrototypeComponentRegistry | undefined {
+  return registries[slug];
+}
+
+export function isAllowedComponentTargetId(
+  segmentId: string,
+  registry: PrototypeComponentRegistry,
+): boolean {
+  if ((registry.ids as readonly string[]).includes(segmentId)) {
+    return true;
+  }
+
+  const prefixes = registry.dynamicPrefixes ?? [];
+  return prefixes.some((prefix) => segmentId.startsWith(prefix));
+}
+
+/** Call from each prototype's component-ids module. */
+export function definePrototypeComponentRegistry(
+  registry: PrototypeComponentRegistry,
+): PrototypeComponentRegistry {
+  return registry;
+}

package/src/lib/prototypes/prototype-config-types.ts

@@ -0,0 +1,34 @@
+import type { ComponentType } from "react";
+
+import type { GalleryConfig } from "@prototype/server/gallery/gallery-types";
+import type { PrototypeComponentRegistry } from "./prototype-component-registry";
+
+export type PrototypeDefinition = {
+  slug: string;
+  title: string;
+  screenshot: string;
+  component: ComponentType;
+  componentRegistry: PrototypeComponentRegistry;
+};
+
+export type PrototypeExtraRoute = {
+  /** URL segments, e.g. `["prototypes", "example-feature", "states"]` or `["section", "[groupId]", "[itemId]", "view"]`. */
+  segments: string[];
+  /** When set, wrap the page in `PrototypeShell` for this slug. */
+  shellSlug?: string;
+  component: ComponentType<Record<string, string>>;
+  componentRegistry?: PrototypeComponentRegistry;
+};
+
+export type PrototypeMetadata = {
+  slug: string;
+  title: string;
+  screenshot: string;
+};
+
+export type PrototypeConfig = {
+  prototypes: PrototypeDefinition[];
+  extraRoutes?: PrototypeExtraRoute[];
+  /** KV + Blob gallery routes at `/api/gallery/*`. Set `false` to disable. */
+  gallery?: GalleryConfig | false;
+};