proto-plugin 0.1.0 → 0.1.2

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

@@ -1,14 +1,16 @@
 import type { ReactNode } from "react";
 
+export type DesignExplorationRationale = {
+  good: string;
+  bad: string;
+};
+
 export type DesignExplorationVariantOption<TVariant extends string> = {
   value: TVariant;
   label: string;
   hint?: string;
-};
-
-export type DesignExplorationRationale = {
-  good: string;
-  bad: string;
+  /** One-line pros/cons shown under the variant title in the design brief. */
+  rationale?: DesignExplorationRationale;
 };
 
 export type DesignExplorationBrief = {
@@ -47,26 +49,82 @@ export type DesignExplorationVariantsSection = {
   description?: string;
 };
 
-/** Persists to KV via `storageKeyPrefix` — use `useDesignExplorationDefault`. */
+/** Pre-exploration UI — always pinned at the bottom of the variant list. */
+export type DesignExplorationBaselineOption<TVariant extends string> = {
+  value: TVariant;
+  /** Shown in the brief and tabs. Default: "Original". */
+  label?: string;
+  hint?: string;
+  rationale?: DesignExplorationRationale;
+};
+
 export type DesignExplorationConfig<TVariant extends string> = {
   componentIdPrefix: string;
   variantTabsIdPrefix: string;
   storageKeyPrefix: string;
   variant: TVariant;
   onVariantChange: (variant: TVariant) => void;
+  /** Layout directions being explored — newest first. Excludes baseline. */
   options: DesignExplorationVariantOption<TVariant>[];
-  rationale: Record<TVariant, DesignExplorationRationale>;
   renderers: Record<TVariant, () => ReactNode>;
   brief: DesignExplorationBrief;
   context?: DesignExplorationContext;
   mobbin?: DesignExplorationMobbin;
   variantsSection?: DesignExplorationVariantsSection;
+  /**
+   * UI state before this exploration was added. Rendered last in the brief
+   * and tabs; deduped from `options` when the same value appears there.
+   */
+  baseline: DesignExplorationBaselineOption<TVariant>;
+  /**
+   * Default variant stored in the codebase (e.g. `DEFAULT_*_VARIANT`). Marks
+   * the "Default" option in the design brief. Falls back to the first option.
+   */
+  defaultVariant?: TVariant;
   /** Label for prev/next variant tab buttons. Default: "variant". */
   variantTabAriaLabel?: string;
-  /** Path to design exploration config — included in reset-brief copy prompt. */
+  /** Path to design exploration config — included in copy prompts. */
   briefConfigFilePath?: string;
 };
 
+export const DESIGN_EXPLORATION_BASELINE_LABEL = "Original";
+
+export function resolveDesignExplorationBaselineOption<
+  TVariant extends string,
+>(
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant> {
+  return {
+    value: baseline.value,
+    label: baseline.label ?? DESIGN_EXPLORATION_BASELINE_LABEL,
+    hint: baseline.hint,
+    rationale: baseline.rationale,
+  };
+}
+
+/** Exploration options only — baseline value removed when duplicated. */
+export function getDesignExplorationVariantOptions<
+  TVariant extends string,
+>(
+  options: DesignExplorationVariantOption<TVariant>[],
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant>[] {
+  return options.filter((option) => option.value !== baseline.value);
+}
+
+/** Exploration options plus baseline pinned at the bottom (for tabs / cycling). */
+export function getDesignExplorationDisplayOptions<
+  TVariant extends string,
+>(
+  options: DesignExplorationVariantOption<TVariant>[],
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant>[] {
+  return [
+    ...getDesignExplorationVariantOptions(options, baseline),
+    resolveDesignExplorationBaselineOption(baseline),
+  ];
+}
+
 /** Plain-text copy of the overview fields as shown in the design brief modal. */
 export function buildBriefOverviewCopyText(
   title: string,
@@ -84,11 +142,13 @@ export function buildCreateDesignExplorationPrompt({
   existingExplorations = [],
   origin = "http://localhost:3003",
   briefText,
+  includeMobbin = true,
 }: {
   slug: string;
   existingExplorations?: Array<{ id: string; label: string }>;
   origin?: string;
   briefText?: string;
+  includeMobbin?: boolean;
 }): string {
   const prototypeUrl = `${origin}/prototypes/${slug}`;
   const variantSetsRegistrar = `src/prototypes/${slug}/_components/*-variant-sets.tsx`;
@@ -122,6 +182,27 @@ export function buildCreateDesignExplorationPrompt({
     "## Prototype",
     `- Slug: \`${slug}\``,
     `- Preview: ${prototypeUrl}`,
+  );
+
+  if (includeMobbin) {
+    lines.push(
+      "",
+      "## Mobbin references",
+      "Before building variants, pull real-world reference screens from Mobbin. Use the Mobbin MCP `search_screens` tool when available; otherwise search on mobbin.com.",
+      "",
+      "1. Search for **3–5 screens** that match the brief and the distinct layout directions you plan to explore. Prefer specific UI descriptions (e.g. \"settings page with profile photo and bio field\") over vague style words.",
+      "2. Pick references that clarify layout, hierarchy, and copy patterns — not just visual polish.",
+      "3. In `*-design-exploration-config.tsx`, add a `mobbin` block:",
+      "   - `references`: `{ id, appName, imageUrl, mobbinUrl, relevance, variantHint? }[]` — use each screen UUID as `id`",
+      "   - `imagePathForReference`: `(id) => \\`/prototypes/mobbin-references/${id}.webp\\``",
+      "4. Register `mobbin-inspiration-gallery` and `mobbin-inspiration-gallery.` in `component-ids.ts` (or pass a custom `mobbinGalleryId` to `PrototypeVariantExplorer`).",
+      "5. Download local assets: `pnpm download-mobbin-references -- --ids=<comma-separated-ids>`",
+      "",
+      "Reference: `src/prototypes/proto-partner-page/_components/invite-copy-design-exploration-config.tsx`.",
+    );
+  }
+
+  lines.push(
     "",
     "## Instructions",
     "Follow AGENTS.md → Design exploration. Do not register a new prototype slug — add a design exploration variant set on this page.",
@@ -129,7 +210,12 @@ export function buildCreateDesignExplorationPrompt({
     "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.",
+    "   - Give this exploration a **distinct Lucide icon** in the review sidebar: add a `{ test, icon }` rule to `packages/prototype/src/lib/prototypes/variant-set-lucide-icon.tsx` that matches its id or label. Place the rule **before** broad matchers (e.g. `/mobile/i`) so it wins. Pick an icon that fits the topic and avoid reusing icons already assigned to other explorations on this prototype — do not leave new explorations on the default `LayoutGrid` fallback or the generic `Smartphone` icon shared by unrelated mobile explorations.",
+    `2. Create \`*-design-exploration-config.tsx\` with options, renderers, brief defaults, baseline,${includeMobbin ? " and the Mobbin references above" : ""}.`,
+    "   - `baseline`: the UI before this exploration existed — `{ value, label?, hint? }`, pinned at the bottom of the variant list.",
+    "   - `options`: layout directions to compare — exclude the baseline value when possible.",
+    "   - Build renderers with `buildDesignExplorationRenderers(options, (variant) => …, baseline)` — one preview per option plus baseline.",
+    "   - Wrap overlay-style variants in `DesignExplorationVariantPreviewShell` with `layout=\"overlay\"` for sidebar previews.",
     "3. Create `*-variant-toggle.tsx` mounting `PrototypeVariantExplorer` with matching `variantSet={{ id, label }}`.",
     "4. Register static ids + any `dynamicPrefixes` in `src/prototypes/" +
       slug +
@@ -149,11 +235,13 @@ export function buildCreateDesignExplorationCopyText({
   existingExplorations = [],
   origin = "http://localhost:3003",
   briefText,
+  includeMobbin = true,
 }: {
   slug: string;
   existingExplorations?: Array<{ id: string; label: string }>;
   origin?: string;
   briefText: string;
+  includeMobbin?: boolean;
 }): string {
   const trimmedBrief = briefText.trim();
   const prompt = buildCreateDesignExplorationPrompt({
@@ -161,6 +249,141 @@ export function buildCreateDesignExplorationCopyText({
     existingExplorations,
     origin,
     briefText: trimmedBrief,
+    includeMobbin,
+  });
+
+  return `${trimmedBrief}\n\n---\n\n${prompt}`;
+}
+
+export function buildMoreDesignExplorationVariantsPrompt({
+  slug,
+  explorationLabel,
+  explorationId,
+  options,
+  brief,
+  configFilePath,
+  origin = "http://localhost:3003",
+  briefText,
+  multipleVersions = true,
+}: {
+  slug: string;
+  explorationLabel: string;
+  explorationId?: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  brief: DesignExplorationBrief;
+  configFilePath?: string;
+  origin?: string;
+  briefText?: string;
+  /** When false, prompt asks for one targeted derivative variant. */
+  multipleVersions?: boolean;
+}): string {
+  const prototypeUrl = `${origin}/prototypes/${slug}`;
+  const configTarget = configFilePath ?? "the design exploration config file";
+  const trimmedBrief = briefText?.trim() ?? "";
+
+  const lines = [
+    `Add new layout variants to the "${explorationLabel}" design exploration on the "${slug}" prototype.`,
+    "",
+    "## Brief",
+  ];
+
+  if (trimmedBrief) {
+    lines.push(trimmedBrief);
+  } else if (multipleVersions) {
+    lines.push(
+      "Describe the new directions to explore:",
+      "- What to try:",
+      "- Target count: 3–5 new variants",
+    );
+  } else {
+    lines.push(
+      "Describe the variation to explore:",
+      "- What to try:",
+      "- Target count: 1 new variant",
+    );
+  }
+
+  lines.push(
+    "",
+    "## Exploration context",
+    `- Label: ${explorationLabel}`,
+  );
+
+  if (explorationId) {
+    lines.push(`- Variant set id: \`${explorationId}\``);
+  }
+
+  lines.push(
+    `- Overview title: ${brief.titleDefault}`,
+    `- Overview description: ${brief.descriptionDefault}`,
+    "",
+    "## Existing variants",
+  );
+
+  for (const option of options) {
+    const hint = option.hint ? ` — ${option.hint}` : "";
+    lines.push(`- ${option.label} (\`${option.value}\`)${hint}`);
+  }
+
+  lines.push(
+    "",
+    "## Prototype",
+    `- Slug: \`${slug}\``,
+    `- Config: \`${configTarget}\``,
+    `- Preview: ${prototypeUrl}`,
+    "",
+    "## Instructions",
+    "Follow AGENTS.md → Design exploration → Iterating on variants.",
+    "",
+    multipleVersions
+      ? "Supply **3–5 new variant options** unless the brief specifies a different count."
+      : "Add **one new derivative variant** unless the brief specifies otherwise.",
+    "",
+    multipleVersions
+      ? "When modifying an existing option, add **new variants** (do not replace in place)."
+      : "When modifying an existing option, add a **single new variant** (do not replace in place). Keep all existing variants.",
+    "",
+    "1. Prepend new entries to the top of `*_VARIANT_OPTIONS` so newest explorations appear first.",
+    "2. Add matching renderers via `buildDesignExplorationRenderers` and any new component ids.",
+    "3. Keep existing variants unless the brief explicitly asks to remove one.",
+    "4. Run `pnpm verify:prototype-ids`.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildMoreDesignExplorationVariantsCopyText({
+  slug,
+  explorationLabel,
+  explorationId,
+  options,
+  brief,
+  configFilePath,
+  origin = "http://localhost:3003",
+  briefText,
+  multipleVersions = true,
+}: {
+  slug: string;
+  explorationLabel: string;
+  explorationId?: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  brief: DesignExplorationBrief;
+  configFilePath?: string;
+  origin?: string;
+  briefText: string;
+  multipleVersions?: boolean;
+}): string {
+  const trimmedBrief = briefText.trim();
+  const prompt = buildMoreDesignExplorationVariantsPrompt({
+    slug,
+    explorationLabel,
+    explorationId,
+    options,
+    brief,
+    configFilePath,
+    origin,
+    briefText: trimmedBrief,
+    multipleVersions,
   });
 
   return `${trimmedBrief}\n\n---\n\n${prompt}`;
@@ -187,9 +410,37 @@ export function buildResetBriefDefaultsPrompt({
   ].join("\n");
 }
 
+/**
+ * Prompt that asks an agent to set the codebase-stored default variant. Copied
+ * by the "Make default" control in the design brief — the default lives in the
+ * config file (e.g. `DEFAULT_*_VARIANT`), not in KV storage.
+ */
+export function buildSetDefaultVariantPrompt({
+  variantLabel,
+  variantValue,
+  configFilePath,
+}: {
+  variantLabel: string;
+  variantValue: string;
+  configFilePath?: string;
+}): string {
+  const target = configFilePath ?? "the design exploration config file";
+
+  return [
+    `Make "${variantLabel}" the default design exploration variant.`,
+    "",
+    `In ${target}, update the exported default variant constant (e.g. \`DEFAULT_*_VARIANT\`) so it equals:`,
+    "",
+    variantValue,
+    "",
+    'This constant is the codebase-stored default the prototype renders first, and the option marked "Default" in the design brief. Keep it as one of the values in the variant options list.',
+  ].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.
+ * design-brief scroll view (see AGENTS.md). The default variant is stored in the
+ * codebase config (`defaultVariant`), not KV.
  */
 export function getAdjacentDesignExplorationVariant<TVariant extends string>(
   options: DesignExplorationVariantOption<TVariant>[],

package/src/lib/prototypes/link-source-prompt.ts

@@ -0,0 +1,93 @@
+export function buildLinkSourcePrompt({
+  sourceInput,
+  description,
+  currentSourcePath,
+  referencePaths = [],
+}: {
+  sourceInput?: string;
+  description?: string;
+  currentSourcePath?: string;
+  referencePaths?: string[];
+} = {}): string {
+  const trimmedInput = sourceInput?.trim();
+  const trimmedDescription = description?.trim();
+  const trimmedCurrent = currentSourcePath?.trim();
+  const isUpdate = Boolean(trimmedCurrent);
+
+  const lines = [
+    isUpdate
+      ? "Update the linked source application for this prototype host app."
+      : "Link the source application for this prototype host app.",
+    "",
+    "## Goal",
+    "Set `SOURCE_PATH` in `.env.local` and run `pnpm link-source` so the `source/` symlink points at the real product repo.",
+  ];
+
+  if (trimmedCurrent) {
+    lines.push("", "## Current source", `- \`SOURCE_PATH\`: \`${trimmedCurrent}\``);
+  }
+
+  lines.push("", "## Desired source");
+
+  if (trimmedInput) {
+    lines.push(`- ${trimmedInput}`);
+    lines.push(
+      "",
+      "Resolve this to a filesystem path (folder name, relative path like `../cal.diy`, or absolute path) before writing `.env.local`.",
+    );
+  } else {
+    lines.push("- (Specify folder name, path, or description above before copying.)");
+  }
+
+  lines.push(
+    "",
+    "## Clarification",
+    "If the input is vague, matches multiple folders on disk, or you cannot confidently identify the correct repo from the description and filesystem, ask the user a clarifying question before changing anything. Do not guess — confirm the exact path first.",
+  );
+
+  if (trimmedDescription) {
+    lines.push("", "## Notes", trimmedDescription);
+  }
+
+  if (referencePaths.length > 0) {
+    lines.push(
+      "",
+      "## Reference screenshots",
+      "Use these files for additional context:",
+    );
+    for (const referencePath of referencePaths) {
+      lines.push(`- \`${referencePath}\``);
+    }
+  }
+
+  lines.push(
+    "",
+    "## Steps",
+    "1. Confirm the correct source path. If it is still unclear after checking the description and filesystem, ask the user before proceeding.",
+    "2. Set or update `SOURCE_PATH` in `.env.local` at the host repo root (see `.env.example`).",
+    "3. Run `pnpm link-source` from the host repo to create or refresh the `source/` symlink.",
+    "4. Restart the dev server if it is already running so env changes are picked up.",
+    "5. Confirm the gallery sidebar footer shows the correct source directory name.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildLinkSourceCopyText({
+  sourcePath,
+  description,
+  currentSourcePath,
+  referencePaths = [],
+}: {
+  sourcePath?: string;
+  description?: string;
+  currentSourcePath?: string;
+  referencePaths?: string[];
+} = {}): string {
+  return buildLinkSourcePrompt({
+    sourceInput: sourcePath,
+    description,
+    currentSourcePath,
+    referencePaths,
+  });
+}

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/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);
+  });
+}