proto-plugin 0.1.0

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

@@ -0,0 +1,96 @@
+import type { PrototypeTweaksRegistration } from "@prototype/lib/prototypes/prototype-tweak-types";
+import { useEffect, useState } from "react";
+
+type PrototypeTweakStore = {
+  registration: PrototypeTweaksRegistration | null;
+  listeners: Set<() => void>;
+};
+
+declare global {
+  interface Window {
+    __prototypeTweakStore?: PrototypeTweakStore;
+  }
+}
+
+function getStore(): PrototypeTweakStore {
+  if (typeof window === "undefined") {
+    return { registration: null, listeners: new Set() };
+  }
+
+  if (!window.__prototypeTweakStore) {
+    window.__prototypeTweakStore = {
+      registration: null,
+      listeners: new Set(),
+    };
+  }
+
+  return window.__prototypeTweakStore;
+}
+
+function emitChange() {
+  for (const listener of getStore().listeners) {
+    listener();
+  }
+}
+
+export function registerPrototypeTweaks(
+  nextRegistration: PrototypeTweaksRegistration | null,
+) {
+  const store = getStore();
+  store.registration = nextRegistration;
+  emitChange();
+}
+
+export function getPrototypeTweaksRegistration() {
+  return getStore().registration;
+}
+
+function subscribe(listener: () => void) {
+  const store = getStore();
+  store.listeners.add(listener);
+  return () => {
+    store.listeners.delete(listener);
+  };
+}
+
+export function subscribePrototypeTweaks(listener: () => void) {
+  return subscribe(listener);
+}
+
+export function usePrototypeTweaksRegistration() {
+  const [registration, setRegistration] =
+    useState<PrototypeTweaksRegistration | null>(() =>
+      typeof window === "undefined" ? null : getPrototypeTweaksRegistration(),
+    );
+
+  useEffect(() => {
+    setRegistration(getPrototypeTweaksRegistration());
+    return subscribe(() => {
+      setRegistration(getPrototypeTweaksRegistration());
+    });
+  }, []);
+
+  return registration;
+}
+
+export function focusPrototypeTweak(tweakId: string) {
+  const activeRegistration = getPrototypeTweaksRegistration();
+  const tweak = activeRegistration?.items.find((item) => item.id === tweakId);
+  if (!tweak) return null;
+
+  activeRegistration?.navigateTo(tweakId);
+
+  window.requestAnimationFrame(() => {
+    window.requestAnimationFrame(() => {
+      const screenshotRoot = document.querySelector(
+        "[data-prototype-screenshot]",
+      );
+      const target = screenshotRoot?.querySelector<HTMLElement>(
+        `[data-prototype-target$=".${tweak.targetId}"]`,
+      );
+      target?.scrollIntoView({ behavior: "smooth", block: "center" });
+    });
+  });
+
+  return tweak.targetId;
+}

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

@@ -0,0 +1,31 @@
+export const PROTOTYPE_TWEAK_CATEGORY_LABELS = {
+  state: "State",
+  variants: "Variants",
+} as const;
+
+export type PrototypeTweakCategory = keyof typeof PROTOTYPE_TWEAK_CATEGORY_LABELS;
+
+export const PROTOTYPE_TWEAK_CATEGORY_ORDER: PrototypeTweakCategory[] = [
+  "state",
+  "variants",
+];
+
+export type PrototypeTweakDefinition = {
+  id: string;
+  label: string;
+  targetId: string;
+  category: PrototypeTweakCategory;
+};
+
+export type PrototypeTweaksRegistration = {
+  items: PrototypeTweakDefinition[];
+  navigateTo: (id: string) => void;
+};
+
+export function groupPrototypeTweaksByCategory(items: PrototypeTweakDefinition[]) {
+  return PROTOTYPE_TWEAK_CATEGORY_ORDER.map((category) => ({
+    category,
+    label: PROTOTYPE_TWEAK_CATEGORY_LABELS[category],
+    items: items.filter((item) => item.category === category),
+  })).filter((group) => group.items.length > 0);
+}

package/src/lib/prototypes/reference-docs.ts

@@ -0,0 +1,137 @@
+export type PrototypeReferenceDoc = {
+  name: string;
+  link: string;
+  content: string;
+};
+
+export function defaultReferenceDocsConfigPath(slug: string): string {
+  return `src/prototypes/${slug}/reference-docs.ts`;
+}
+
+export function isValidReferenceDoc(value: unknown): value is PrototypeReferenceDoc {
+  if (!value || typeof value !== "object") return false;
+
+  const doc = value as Partial<PrototypeReferenceDoc>;
+
+  if (typeof doc.name !== "string" || !doc.name.trim()) return false;
+  if (typeof doc.link !== "string" || !doc.link.trim()) return false;
+  if (typeof doc.content !== "string") return false;
+
+  try {
+    const url = new URL(normalizeReferenceDocLink(doc.link));
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function normalizeReferenceDocLink(link: string): string {
+  const trimmed = link.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    return trimmed;
+  }
+  return `https://${trimmed}`;
+}
+
+export function isValidReferenceDocInput(
+  name: string,
+  link: string,
+  content: string,
+): boolean {
+  if (!name.trim() || !link.trim() || !content.trim()) return false;
+
+  try {
+    const url = new URL(normalizeReferenceDocLink(link));
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function buildAddReferenceDocPrompt({
+  slug,
+  name,
+  link,
+  content,
+  existingDocs = [],
+  configFilePath,
+  origin = "http://localhost:3003",
+}: {
+  slug: string;
+  name: string;
+  link: string;
+  content: string;
+  existingDocs?: PrototypeReferenceDoc[];
+  configFilePath?: string;
+  origin?: string;
+}): string {
+  const target = configFilePath ?? defaultReferenceDocsConfigPath(slug);
+  const prototypeUrl = `${origin}/prototypes/${slug}`;
+  const trimmedName = name.trim();
+  const trimmedLink = normalizeReferenceDocLink(link);
+  const trimmedContent = content.trim();
+
+  const lines = [
+    `Add a reference doc to the "${slug}" prototype.`,
+    "",
+    "## Doc",
+    `Name: ${trimmedName}`,
+    `Link: ${trimmedLink}`,
+    "",
+    "Content:",
+    trimmedContent,
+  ];
+
+  if (existingDocs.length > 0) {
+    lines.push("", "## Existing reference docs");
+    for (const doc of existingDocs) {
+      lines.push(`- ${doc.name} (${doc.link})`);
+    }
+  }
+
+  lines.push(
+    "",
+    "## Prototype",
+    `- Slug: \`${slug}\``,
+    `- Preview: ${prototypeUrl}`,
+    "",
+    "## Instructions",
+    `1. Create or update \`${target}\` and export \`REFERENCE_DOCS\` as a \`PrototypeReferenceDoc[]\` array.`,
+    "2. Prepend the new doc to the top of the array so the newest reference appears first.",
+    "3. Each entry must include `name`, `link`, and `content`.",
+    "4. Wire the docs on the prototype page with `useRegisterPrototypeReferenceDocs(REFERENCE_DOCS)` from `prototype`.",
+    "5. Do not store reference docs in KV or localStorage.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildAddReferenceDocCopyText({
+  slug,
+  name,
+  link,
+  content,
+  existingDocs = [],
+  configFilePath,
+  origin = "http://localhost:3003",
+}: {
+  slug: string;
+  name: string;
+  link: string;
+  content: string;
+  existingDocs?: PrototypeReferenceDoc[];
+  configFilePath?: string;
+  origin?: string;
+}): string {
+  const prompt = buildAddReferenceDocPrompt({
+    slug,
+    name,
+    link,
+    content,
+    existingDocs,
+    configFilePath,
+    origin,
+  });
+
+  return `${content.trim()}\n\n---\n\n${prompt}`;
+}

package/src/lib/prototypes/screenshot-manifest.ts

@@ -0,0 +1,33 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import path from "path";
+
+type ScreenshotManifest = Record<string, number>;
+
+const MANIFEST_PATH = path.join(
+  process.cwd(),
+  "public/prototypes/screenshots/manifest.json",
+);
+
+export async function readScreenshotManifest(): Promise<ScreenshotManifest> {
+  try {
+    const raw = await readFile(MANIFEST_PATH, "utf-8");
+    return JSON.parse(raw) as ScreenshotManifest;
+  } catch {
+    return {};
+  }
+}
+
+export async function touchScreenshotManifestKey(key: string): Promise<number> {
+  const manifest = await readScreenshotManifest();
+  const version = Date.now();
+  manifest[key] = version;
+
+  await mkdir(path.dirname(MANIFEST_PATH), { recursive: true });
+  await writeFile(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  return version;
+}
+
+export async function touchScreenshotManifest(slug: string): Promise<number> {
+  return touchScreenshotManifestKey(slug);
+}

package/src/lib/prototypes/screenshot-src.ts

@@ -0,0 +1,7 @@
+export function screenshotSrc(
+  basePath: string,
+  version: number | undefined,
+): string {
+  if (!version) return basePath;
+  return `${basePath}?v=${version}`;
+}

package/src/lib/prototypes/share-command.ts

@@ -0,0 +1,8 @@
+export function getPrototypeShareCommand(slug: string): string {
+  return `pnpm share-prototype ${slug}`;
+}
+
+export function getPrototypeSlugFromPathname(pathname: string): string | null {
+  const match = pathname.match(/^\/prototypes\/([^/]+)/);
+  return match?.[1] ?? null;
+}

package/src/lib/prototypes/state-map-annotation.ts

@@ -0,0 +1,70 @@
+export type ParsedStateMapBullet = {
+  text: string;
+  index: number;
+  highlightId?: string;
+};
+
+export type ParsedStateMapAnnotation = {
+  lead: string;
+  bullets: ParsedStateMapBullet[];
+};
+
+const BULLET_LINE = /^\s*[•*-]\s+(.+)$/;
+const HIGHLIGHT_SUFFIX = /\s+@([a-z0-9-]+)$/i;
+
+export function parseStateMapAnnotation(text: string): ParsedStateMapAnnotation {
+  const lines = text.split("\n");
+  const leadLines: string[] = [];
+  const bullets: ParsedStateMapBullet[] = [];
+  let bulletIndex = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      if (leadLines.length > 0 && bullets.length === 0) {
+        leadLines.push("");
+      }
+      continue;
+    }
+
+    const bulletMatch = trimmed.match(BULLET_LINE);
+    if (bulletMatch) {
+      let body = bulletMatch[1]!.trim();
+      let highlightId: string | undefined;
+      const highlightMatch = body.match(HIGHLIGHT_SUFFIX);
+      if (highlightMatch) {
+        highlightId = highlightMatch[1]!.toLowerCase();
+        body = body.slice(0, highlightMatch.index).trim();
+      }
+      bullets.push({ text: body, index: bulletIndex, highlightId });
+      bulletIndex += 1;
+      continue;
+    }
+
+    if (bullets.length === 0) {
+      leadLines.push(trimmed);
+    }
+  }
+
+  return { lead: leadLines.join("\n").trim(), bullets };
+}
+
+export function resolveBulletHighlightId(
+  bullet: ParsedStateMapBullet,
+  highlightRegions?: readonly string[],
+): string | null {
+  if (bullet.highlightId) return bullet.highlightId;
+  return highlightRegions?.[bullet.index] ?? null;
+}
+
+export function stateMapAnnotationHasInteractiveBullets(
+  text: string,
+  highlightRegions?: readonly string[],
+): boolean {
+  const { bullets } = parseStateMapAnnotation(text);
+  if (bullets.length === 0) return false;
+  if (!highlightRegions?.length) {
+    return bullets.some((bullet) => bullet.highlightId);
+  }
+  return true;
+}

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

@@ -0,0 +1,114 @@
+"use client";
+
+import { createDesignExplorationDefaultStorageAdapter } from "@prototype/lib/prototypes/design-exploration-default-storage";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+type UseDesignExplorationDefaultOptions<TVariant extends string> = {
+  slug: string | null;
+  storageKeyPrefix: string;
+  validValues: readonly TVariant[];
+};
+
+export function useDesignExplorationDefault<TVariant extends string>({
+  slug,
+  storageKeyPrefix,
+  validValues,
+}: UseDesignExplorationDefaultOptions<TVariant>) {
+  const [persistedDefault, setPersistedDefault] = useState<TVariant | null>(null);
+  const [ready, setReady] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const storage = useMemo(() => {
+    if (!slug) return null;
+    return createDesignExplorationDefaultStorageAdapter(slug, storageKeyPrefix);
+  }, [slug, storageKeyPrefix]);
+
+  useEffect(() => {
+    if (!storage) {
+      setReady(true);
+      return;
+    }
+
+    let cancelled = false;
+    setReady(false);
+    setError(null);
+
+    async function load() {
+      const activeStorage = storage;
+      if (!activeStorage) return;
+
+      try {
+        const record = await activeStorage.load();
+        if (cancelled) return;
+
+        if (
+          record &&
+          validValues.includes(record.value as TVariant)
+        ) {
+          setPersistedDefault(record.value as TVariant);
+        } else {
+          setPersistedDefault(null);
+        }
+      } catch (loadError) {
+        if (!cancelled) {
+          setError(
+            loadError instanceof Error
+              ? loadError.message
+              : "Failed to load design default variant.",
+          );
+          setPersistedDefault(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setReady(true);
+        }
+      }
+    }
+
+    void load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, validValues]);
+
+  const effectiveDefault = persistedDefault ?? validValues[0];
+
+  const setDefaultVariant = useCallback(
+    async (value: TVariant) => {
+      if (!validValues.includes(value)) return;
+
+      setPersistedDefault(value);
+
+      if (!storage) return;
+
+      setSaving(true);
+      setError(null);
+
+      try {
+        await storage.save({
+          value,
+          updatedAt: new Date().toISOString(),
+        });
+      } catch (saveError) {
+        setError(
+          saveError instanceof Error
+            ? saveError.message
+            : "Failed to save design default variant.",
+        );
+      } finally {
+        setSaving(false);
+      }
+    },
+    [storage, validValues],
+  );
+
+  return {
+    effectiveDefault,
+    setDefaultVariant,
+    ready,
+    saving,
+    error,
+  };
+}

package/src/lib/prototypes/use-persisted-local-state.ts

@@ -0,0 +1,140 @@
+"use client";
+
+import {
+  hasPendingCommentRestore,
+  readShareCommentParam,
+  readShareLinkParams,
+} from "@prototype/lib/prototypes/prototype-share-link";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export function prototypeLiveStateStorageKey(slug: string): string {
+  return `prototype-live-state:${slug}`;
+}
+
+export function prototypeReviewPreferenceKey(
+  slug: string,
+  preference: string,
+): string {
+  return `prototype-review:${slug}:${preference}`;
+}
+
+export function readPersistedPrototypeLiveState<T>(
+  slug: string,
+  revive?: (parsed: unknown) => T | null,
+): T | null {
+  if (typeof window === "undefined") return null;
+
+  try {
+    const searchParams = new URLSearchParams(window.location.search);
+    if (
+      readShareLinkParams(searchParams) ||
+      readShareCommentParam(searchParams) ||
+      hasPendingCommentRestore(slug)
+    ) {
+      return null;
+    }
+
+    const raw = localStorage.getItem(prototypeLiveStateStorageKey(slug));
+    if (!raw) return null;
+
+    const parsed: unknown = JSON.parse(raw);
+    return revive ? revive(parsed) : (parsed as T);
+  } catch {
+    return null;
+  }
+}
+
+export function writePersistedPrototypeLiveState(
+  slug: string,
+  state: unknown,
+): void {
+  if (typeof window === "undefined") return;
+
+  try {
+    localStorage.setItem(
+      prototypeLiveStateStorageKey(slug),
+      JSON.stringify(state),
+    );
+  } catch {
+    // Ignore localStorage write failures in prototype preview.
+  }
+}
+
+/** Persists prototype live state to localStorage on change (skips share-link loads). */
+export function usePersistPrototypeLiveState<T extends Record<string, unknown>>(
+  slug: string,
+  state: T,
+  enabled = true,
+): void {
+  const hasHydratedRef = useRef(false);
+  const serializedState = JSON.stringify(state);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    if (!hasHydratedRef.current) {
+      hasHydratedRef.current = true;
+      return;
+    }
+
+    writePersistedPrototypeLiveState(slug, JSON.parse(serializedState) as T);
+  }, [enabled, serializedState, slug]);
+}
+
+export function usePersistedLocalString(storageKey: string, defaultValue: string) {
+  const [value, setValue] = useState(defaultValue);
+
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored != null) {
+        setValue(stored);
+      }
+    } catch {
+      // Ignore localStorage read failures in prototype preview.
+    }
+  }, [storageKey]);
+
+  const updateValue = useCallback(
+    (nextValue: string) => {
+      setValue(nextValue);
+      try {
+        localStorage.setItem(storageKey, nextValue);
+      } catch {
+        // Ignore localStorage write failures in prototype preview.
+      }
+    },
+    [storageKey],
+  );
+
+  return { value, updateValue };
+}
+
+export function usePersistedLocalBoolean(storageKey: string, defaultValue: boolean) {
+  const [value, setValue] = useState(defaultValue);
+
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored != null) {
+        setValue(stored === "true");
+      }
+    } catch {
+      // Ignore localStorage read failures in prototype preview.
+    }
+  }, [storageKey]);
+
+  const updateValue = useCallback(
+    (nextValue: boolean) => {
+      setValue(nextValue);
+      try {
+        localStorage.setItem(storageKey, String(nextValue));
+      } catch {
+        // Ignore localStorage write failures in prototype preview.
+      }
+    },
+    [storageKey],
+  );
+
+  return { value, updateValue };
+}

package/src/lib/prototypes/use-prototype-comments.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+import type { AnnotationTargetOptions } from "@prototype/lib/prototype-comments/core/annotation-target";
+
+import {
+  usePrototypeCommentRegistry,
+  type PrototypeCommentHandlers,
+} from "./prototype-comment-registry";
+
+type UsePrototypeCommentsOptions = {
+  resolveTargetOptions?: () => AnnotationTargetOptions;
+};
+
+/**
+ * Register live state snapshot/restore handlers for the prototype comment system.
+ * Call from each prototype that wants controls/filter state frozen in annotations.
+ */
+export function usePrototypeComments<TLive extends Record<string, unknown>>(
+  live: TLive,
+  onRestore: (live: TLive) => void,
+  options?: UsePrototypeCommentsOptions,
+) {
+  const { register, unregister, notifyLiveStateChange } =
+    usePrototypeCommentRegistry();
+  const liveRef = useRef(live);
+  const onRestoreRef = useRef(onRestore);
+  const resolveTargetOptionsRef = useRef(options?.resolveTargetOptions);
+
+  liveRef.current = live;
+  onRestoreRef.current = onRestore;
+  resolveTargetOptionsRef.current = options?.resolveTargetOptions;
+
+  const lastSerializedRef = useRef<string | null>(null);
+  useEffect(() => {
+    const serialized = JSON.stringify(live);
+    if (
+      lastSerializedRef.current !== null &&
+      lastSerializedRef.current !== serialized
+    ) {
+      notifyLiveStateChange();
+    }
+    lastSerializedRef.current = serialized;
+  }, [live, notifyLiveStateChange]);
+
+  useLayoutEffect(() => {
+    const handlers: PrototypeCommentHandlers = {
+      getLiveState: () => liveRef.current,
+      onRestore: (restored) => {
+        onRestoreRef.current(restored as TLive);
+      },
+      ...(resolveTargetOptionsRef.current
+        ? {
+            resolveTargetOptions: () =>
+              resolveTargetOptionsRef.current?.() ?? {},
+          }
+        : {}),
+    };
+    register(handlers);
+    return () => unregister(handlers);
+  }, [register, unregister]);
+}