proto-plugin 0.1.0

package/src/lib/prototype-comments/ui/is-comment-detail-path.ts

@@ -0,0 +1,7 @@
+export function isCanvasPath(pathname: string, basePath = "/canvas"): boolean {
+  return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}
+
+export function isCanvasDetailPath(pathname: string, basePath = "/canvas"): boolean {
+  return pathname !== basePath && pathname.startsWith(`${basePath}/`);
+}

package/src/lib/prototypes/capture-prototype-viewport.ts

@@ -0,0 +1,32 @@
+import { toPng } from "html-to-image";
+
+const DEFAULT_CAPTURE_DELAY_MS = 600;
+
+export async function capturePrototypeViewportPng(
+  delayMs = DEFAULT_CAPTURE_DELAY_MS,
+): Promise<string | null> {
+  const root = document.querySelector<HTMLElement>("[data-prototype-screenshot]");
+  if (!root) return null;
+
+  await document.fonts.ready;
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+
+  const pixelRatio = Math.max(2, window.devicePixelRatio || 1);
+
+  return toPng(root, {
+    pixelRatio,
+    cacheBust: true,
+    width: root.clientWidth,
+    height: root.clientHeight,
+    filter: (node) => {
+      if (!(node instanceof HTMLElement)) return true;
+      if (node.dataset.prototypeControls !== undefined) return false;
+      if (node.dataset.prototypeCommentRoot !== undefined) return false;
+      if (node.closest("[data-prototype-comment-root]")) return false;
+      if (node.dataset.commentCaptureToolbar !== undefined) return false;
+      if (node.dataset.commentsSidebar !== undefined) return false;
+      if (node.dataset.prototypeStateCanvas !== undefined) return false;
+      return true;
+    },
+  });
+}

package/src/lib/prototypes/changelog-meta-context.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import { createChangelogMetaStorageAdapter } from "@prototype/lib/prototypes/changelog-meta-storage";
+import {
+  EMPTY_CHANGELOG_META,
+  mergeLegacyChangelogMeta,
+  type PrototypeChangelogMeta,
+} from "@prototype/lib/prototypes/changelog-meta";
+import { prototypeReviewPreferenceKey } from "@prototype/lib/prototypes/use-persisted-local-state";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+type ChangelogMetaStore = {
+  slug: string;
+  overview: string;
+  ready: boolean;
+  error: string | null;
+  setOverview: (overview: string) => void;
+};
+
+const ChangelogMetaContext = createContext<ChangelogMetaStore | null>(null);
+
+const SAVE_DEBOUNCE_MS = 400;
+
+type ChangelogMetaProviderProps = {
+  slug: string;
+  children: ReactNode;
+};
+
+export function ChangelogMetaProvider({
+  slug,
+  children,
+}: ChangelogMetaProviderProps) {
+  const [meta, setMeta] = useState<PrototypeChangelogMeta>(EMPTY_CHANGELOG_META);
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const skipSaveRef = useRef(true);
+  const legacyOverviewKey = prototypeReviewPreferenceKey(
+    slug,
+    "changelog-overview",
+  );
+
+  const storage = useMemo(
+    () => createChangelogMetaStorageAdapter(slug),
+    [slug],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    skipSaveRef.current = true;
+
+    async function load() {
+      setReady(false);
+      setError(null);
+
+      try {
+        const remote = await storage.load();
+        if (cancelled) return;
+
+        const merged = mergeLegacyChangelogMeta(
+          remote,
+          slug,
+          legacyOverviewKey,
+        );
+        setMeta(merged);
+
+        const migratedFromLegacy = merged.overview !== remote.overview;
+
+        if (migratedFromLegacy) {
+          await storage.save(merged);
+        }
+      } catch (loadError) {
+        if (!cancelled) {
+          setError(
+            loadError instanceof Error
+              ? loadError.message
+              : "Failed to load change log.",
+          );
+          setMeta(EMPTY_CHANGELOG_META);
+        }
+      } finally {
+        if (!cancelled) {
+          setReady(true);
+        }
+      }
+    }
+
+    void load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [legacyOverviewKey, slug, storage]);
+
+  useEffect(() => {
+    if (!ready) return;
+
+    if (skipSaveRef.current) {
+      skipSaveRef.current = false;
+      return;
+    }
+
+    const timeout = window.setTimeout(() => {
+      void storage.save(meta).catch((saveError) => {
+        setError(
+          saveError instanceof Error
+            ? saveError.message
+            : "Failed to save change log.",
+        );
+      });
+    }, SAVE_DEBOUNCE_MS);
+
+    return () => {
+      window.clearTimeout(timeout);
+    };
+  }, [meta, ready, storage]);
+
+  const setOverview = useCallback((overview: string) => {
+    setMeta((current) => ({
+      ...current,
+      overview,
+      updatedAt: new Date().toISOString(),
+    }));
+  }, []);
+
+  const value = useMemo(
+    (): ChangelogMetaStore => ({
+      slug,
+      overview: meta.overview,
+      ready,
+      error,
+      setOverview,
+    }),
+    [slug, meta.overview, ready, error, setOverview],
+  );
+
+  return (
+    <ChangelogMetaContext.Provider value={value}>
+      {children}
+    </ChangelogMetaContext.Provider>
+  );
+}
+
+export function useChangelogMeta(): ChangelogMetaStore {
+  const context = useContext(ChangelogMetaContext);
+  if (!context) {
+    throw new Error("useChangelogMeta must be used within ChangelogMetaProvider");
+  }
+  return context;
+}
+
+export function useChangelogMetaOptional(): ChangelogMetaStore | null {
+  return useContext(ChangelogMetaContext);
+}

package/src/lib/prototypes/changelog-meta-storage.ts

@@ -0,0 +1,62 @@
+import {
+  parseChangelogMeta,
+  type PrototypeChangelogMeta,
+} from "./changelog-meta";
+
+export class ChangelogMetaStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChangelogMetaStorageError";
+  }
+}
+
+export function createChangelogMetaStorageAdapter(slug: string) {
+  const url = `/api/prototypes/${encodeURIComponent(slug)}/changelog-meta`;
+
+  return {
+    async load(): Promise<PrototypeChangelogMeta> {
+      const response = await fetch(url);
+
+      if (response.status === 503) {
+        throw new ChangelogMetaStorageError(
+          "Change log storage is not configured. Set Upstash Redis env vars.",
+        );
+      }
+
+      if (!response.ok) {
+        const body = (await response.json().catch(() => null)) as {
+          error?: string;
+        } | null;
+        throw new ChangelogMetaStorageError(
+          body?.error ?? "Failed to load change log overview.",
+        );
+      }
+
+      const parsed: unknown = await response.json();
+      return parseChangelogMeta(parsed);
+    },
+
+    async save(meta: PrototypeChangelogMeta): Promise<void> {
+      const response = await fetch(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(meta),
+      });
+
+      if (response.status === 503) {
+        throw new ChangelogMetaStorageError(
+          "Change log storage is not configured. Set Upstash Redis env vars.",
+        );
+      }
+
+      if (!response.ok) {
+        const body = (await response.json().catch(() => null)) as {
+          error?: string;
+        } | null;
+        throw new ChangelogMetaStorageError(
+          body?.error ?? "Failed to save change log overview.",
+        );
+      }
+    },
+  };
+}

package/src/lib/prototypes/changelog-meta.ts

@@ -0,0 +1,95 @@
+export type PrototypeChangelogMeta = {
+  overview: string;
+  updatedAt: string;
+};
+
+export function prototypeChangelogMetaRedisKey(slug: string): string {
+  return `prototype-changelog-meta:${slug}`;
+}
+
+export function parseChangelogMeta(value: unknown): PrototypeChangelogMeta {
+  if (!value || typeof value !== "object") {
+    return EMPTY_CHANGELOG_META;
+  }
+
+  const meta = value as Partial<PrototypeChangelogMeta>;
+
+  if (
+    typeof meta.overview !== "string" ||
+    typeof meta.updatedAt !== "string" ||
+    Number.isNaN(Date.parse(meta.updatedAt))
+  ) {
+    return EMPTY_CHANGELOG_META;
+  }
+
+  return {
+    overview: meta.overview,
+    updatedAt: meta.updatedAt,
+  };
+}
+
+export function isValidChangelogMeta(value: unknown): value is PrototypeChangelogMeta {
+  if (!value || typeof value !== "object") return false;
+
+  const meta = value as Partial<PrototypeChangelogMeta>;
+
+  if (typeof meta.overview !== "string") return false;
+  if (
+    typeof meta.updatedAt !== "string" ||
+    Number.isNaN(Date.parse(meta.updatedAt))
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+export function normalizeChangelogMetaPayload(
+  value: unknown,
+): PrototypeChangelogMeta | null {
+  if (!isValidChangelogMeta(value)) return null;
+
+  const meta = value as Partial<PrototypeChangelogMeta>;
+
+  return {
+    overview: meta.overview ?? "",
+    updatedAt: meta.updatedAt ?? new Date().toISOString(),
+  };
+}
+
+export const EMPTY_CHANGELOG_META: PrototypeChangelogMeta = {
+  overview: "",
+  updatedAt: new Date(0).toISOString(),
+};
+
+/** One-time merge from legacy browser storage when Redis has no saved meta yet. */
+export function mergeLegacyChangelogMeta(
+  remote: PrototypeChangelogMeta,
+  _slug: string,
+  legacyOverviewKey: string,
+): PrototypeChangelogMeta {
+  if (typeof window === "undefined") return remote;
+
+  const hasRemoteContent = remote.overview.trim().length > 0;
+  if (hasRemoteContent) return remote;
+
+  let overview = remote.overview;
+
+  try {
+    const legacyOverview = localStorage.getItem(legacyOverviewKey);
+    if (legacyOverview?.trim()) {
+      overview = legacyOverview;
+    }
+  } catch {
+    // ignore
+  }
+
+  if (overview === remote.overview) {
+    return remote;
+  }
+
+  return {
+    overview,
+    updatedAt: new Date().toISOString(),
+  };
+}

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

@@ -0,0 +1,74 @@
+import type {
+  PrototypeConfig,
+  PrototypeMetadata,
+} from "./prototype-config-types";
+import type { PrototypeComponentRegistry } from "./prototype-component-registry";
+
+let activeConfig: PrototypeConfig | null = null;
+
+export function setPrototypeConfig(config: PrototypeConfig): void {
+  activeConfig = config;
+}
+
+function requireConfig(): PrototypeConfig {
+  if (!activeConfig) {
+    throw new Error(
+      "Prototype config is not set. Import prototype.config.ts and call setPrototypeConfig() or createPrototypeRegistry() first.",
+    );
+  }
+  return activeConfig;
+}
+
+export function createPrototypeRegistry(config: PrototypeConfig) {
+  setPrototypeConfig(config);
+
+  return {
+    getAllPrototypes(): PrototypeMetadata[] {
+      return requireConfig().prototypes.map(
+        ({ slug, title, screenshot }) => ({ slug, title, screenshot }),
+      );
+    },
+
+    getPrototype(slug: string): PrototypeMetadata | undefined {
+      const entry = requireConfig().prototypes.find((prototype) => prototype.slug === slug);
+      if (!entry) return undefined;
+      return { slug: entry.slug, title: entry.title, screenshot: entry.screenshot };
+    },
+
+    getPrototypeComponent(slug: string) {
+      return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+        ?.component;
+    },
+
+    getPrototypeComponentRegistryForSlug(
+      slug: string,
+    ): PrototypeComponentRegistry | undefined {
+      return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+        ?.componentRegistry;
+    },
+  };
+}
+
+export function getPrototypeComponentRegistryForSlug(
+  slug: string,
+): PrototypeComponentRegistry | undefined {
+  return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+    ?.componentRegistry;
+}
+
+export function getAllPrototypes(): PrototypeMetadata[] {
+  return requireConfig().prototypes.map(({ slug, title, screenshot }) => ({
+    slug,
+    title,
+    screenshot,
+  }));
+}
+
+export function getPrototype(slug: string): PrototypeMetadata | undefined {
+  return getAllPrototypes().find((prototype) => prototype.slug === slug);
+}
+
+export function getPrototypeComponent(slug: string) {
+  return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+    ?.component;
+}

package/src/lib/prototypes/create-state-screenshot-thumbnail.ts

@@ -0,0 +1,46 @@
+function loadImage(dataUrl: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error("Failed to load screenshot image"));
+    img.src = dataUrl;
+  });
+}
+
+/** Crop and resize a viewport capture to match state-map preview (object-cover, top). */
+export async function createStateScreenshotThumbnail(
+  sourceDataUrl: string,
+  targetWidth: number,
+  targetHeight: number,
+): Promise<string | null> {
+  try {
+    const img = await loadImage(sourceDataUrl);
+    const canvas = document.createElement("canvas");
+    canvas.width = targetWidth;
+    canvas.height = targetHeight;
+
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+
+    const sourceAspect = img.width / img.height;
+    const targetAspect = targetWidth / targetHeight;
+
+    let sx = 0;
+    let sy = 0;
+    let sw = img.width;
+    let sh = img.height;
+
+    if (sourceAspect > targetAspect) {
+      sw = img.height * targetAspect;
+      sx = (img.width - sw) / 2;
+    } else {
+      sh = img.width / targetAspect;
+      sy = 0;
+    }
+
+    ctx.drawImage(img, sx, sy, sw, sh, 0, 0, targetWidth, targetHeight);
+    return canvas.toDataURL("image/png");
+  } catch {
+    return null;
+  }
+}

package/src/lib/prototypes/design-exploration-default-storage.ts

@@ -0,0 +1,68 @@
+import {
+  parseDesignExplorationDefault,
+  type DesignExplorationDefaultRecord,
+} from "./design-exploration-default";
+
+export class DesignExplorationDefaultStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DesignExplorationDefaultStorageError";
+  }
+}
+
+export function createDesignExplorationDefaultStorageAdapter(
+  slug: string,
+  storageKeyPrefix: string,
+) {
+  const params = new URLSearchParams({ key: storageKeyPrefix });
+  const url = `/api/prototypes/${encodeURIComponent(slug)}/design-exploration-default?${params}`;
+
+  return {
+    async load(): Promise<DesignExplorationDefaultRecord | null> {
+      const response = await fetch(url);
+
+      if (response.status === 503) {
+        throw new DesignExplorationDefaultStorageError(
+          "Design default storage is not configured. Set Upstash Redis env vars.",
+        );
+      }
+
+      if (!response.ok) {
+        const body = (await response.json().catch(() => null)) as {
+          error?: string;
+        } | null;
+        throw new DesignExplorationDefaultStorageError(
+          body?.error ?? "Failed to load design default variant.",
+        );
+      }
+
+      const parsed: unknown = await response.json();
+      if (parsed == null) return null;
+
+      return parseDesignExplorationDefault(parsed);
+    },
+
+    async save(record: DesignExplorationDefaultRecord): Promise<void> {
+      const response = await fetch(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(record),
+      });
+
+      if (response.status === 503) {
+        throw new DesignExplorationDefaultStorageError(
+          "Design default storage is not configured. Set Upstash Redis env vars.",
+        );
+      }
+
+      if (!response.ok) {
+        const body = (await response.json().catch(() => null)) as {
+          error?: string;
+        } | null;
+        throw new DesignExplorationDefaultStorageError(
+          body?.error ?? "Failed to save design default variant.",
+        );
+      }
+    },
+  };
+}

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

@@ -0,0 +1,51 @@
+export type DesignExplorationDefaultRecord = {
+  value: string;
+  updatedAt: string;
+};
+
+export function prototypeDesignExplorationDefaultRedisKey(
+  storageKeyPrefix: string,
+): string {
+  return `prototype-design-default:${storageKeyPrefix}`;
+}
+
+export function parseDesignExplorationDefault(
+  value: unknown,
+): DesignExplorationDefaultRecord | null {
+  if (!value || typeof value !== "object") return null;
+
+  const record = value as Partial<DesignExplorationDefaultRecord>;
+
+  if (typeof record.value !== "string" || !record.value.trim()) return null;
+  if (
+    typeof record.updatedAt !== "string" ||
+    Number.isNaN(Date.parse(record.updatedAt))
+  ) {
+    return null;
+  }
+
+  return {
+    value: record.value,
+    updatedAt: record.updatedAt,
+  };
+}
+
+export function isValidDesignExplorationDefaultRecord(
+  value: unknown,
+): value is DesignExplorationDefaultRecord {
+  return parseDesignExplorationDefault(value) != null;
+}
+
+export function normalizeDesignExplorationDefaultPayload(
+  value: unknown,
+  validValues?: readonly string[],
+): DesignExplorationDefaultRecord | null {
+  const parsed = parseDesignExplorationDefault(value);
+  if (!parsed) return null;
+
+  if (validValues && !validValues.includes(parsed.value)) {
+    return null;
+  }
+
+  return parsed;
+}