proto-plugin 0.1.0

package/src/components/prototypes/prototype-state-canvas.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { usePrototypeReviewOptional } from "@prototype/lib/prototypes/prototype-review-context";
+import { useEffect } from "react";
+
+export function PrototypeStateCanvasRegistrar({
+  pagePath,
+}: {
+  pagePath: string;
+}) {
+  const review = usePrototypeReviewOptional();
+
+  useEffect(() => {
+    review?.setStateCanvasPagePath(pagePath);
+    return () => review?.setStateCanvasPagePath(null);
+  }, [pagePath, review]);
+
+  return null;
+}
+
+export { PrototypeStateCanvasView } from "@prototype/components/prototypes/prototype-state-canvas-overlay";
+
+export type { PrototypeStateCanvasConfig } from "@prototype/lib/prototypes/prototype-state-canvas-types";
+export {
+  buildStateMapHref,
+  buildStateMapAnnotationEntries,
+  getDefaultPrototypeStateMapPath,
+  parseStateMapReturnTo,
+  PROTOTYPE_STATE_MAP_RETURN_TO_PARAM,
+  stateMapHasAnnotations,
+} from "@prototype/lib/prototypes/prototype-state-canvas-types";
+export type {
+  PrototypeStateCanvasEdge,
+  PrototypeStateCanvasNode,
+  PrototypeStateCanvasNodeCallout,
+  PrototypeStateCanvasSection,
+  PrototypeStateMapAnnotationEntry,
+} from "@prototype/lib/prototypes/prototype-state-canvas-types";

package/src/components/prototypes/prototype-state-screenshot-preview.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { getStateScreenshotThumbSize } from "@prototype/lib/prototypes/prototype-state-canvas-constants";
+import { usePrototypeStateScreenshotSrc } from "@prototype/lib/prototypes/use-prototype-state-screenshot-src";
+import { useEffect, useState, type ReactNode } from "react";
+
+import { cn } from "@prototype/lib/utils";
+
+const THUMB_SIZE = getStateScreenshotThumbSize();
+
+type PrototypeStateScreenshotPreviewProps = {
+  slug: string;
+  stateId: string;
+  fallback: ReactNode;
+  className?: string;
+};
+
+export function PrototypeStateScreenshotPreview({
+  slug,
+  stateId,
+  fallback,
+  className,
+}: PrototypeStateScreenshotPreviewProps) {
+  const src = usePrototypeStateScreenshotSrc(slug, stateId);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    setFailed(false);
+  }, [src]);
+
+  if (!src || failed) {
+    return <>{fallback}</>;
+  }
+
+  return (
+    <img
+      src={src}
+      alt=""
+      aria-hidden
+      width={THUMB_SIZE.width}
+      height={THUMB_SIZE.height}
+      decoding="sync"
+      className={cn("block h-full w-full object-cover object-top", className)}
+      onError={() => setFailed(true)}
+    />
+  );
+}

package/src/components/prototypes/prototype-target.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  type ComponentPropsWithoutRef,
+  type ElementType,
+  type ReactNode,
+} from "react";
+
+import {
+  isAllowedComponentTargetId,
+  type PrototypeComponentRegistry,
+} from "@prototype/lib/prototypes/prototype-component-registry";
+import { cn } from "@prototype/lib/utils";
+
+export const PROTOTYPE_TARGET_ATTR = "data-prototype-target";
+
+const PrototypeSlugContext = createContext<string | null>(null);
+const PrototypeRegistryContext =
+  createContext<PrototypeComponentRegistry | null>(null);
+
+export function PrototypeTargetIdProvider({
+  slug,
+  registry,
+  children,
+}: {
+  slug: string;
+  registry?: PrototypeComponentRegistry;
+  children: ReactNode;
+}) {
+  return (
+    <PrototypeSlugContext.Provider value={slug}>
+      <PrototypeRegistryContext.Provider value={registry ?? null}>
+        {children}
+      </PrototypeRegistryContext.Provider>
+    </PrototypeSlugContext.Provider>
+  );
+}
+
+export function usePrototypeSlug(): string | null {
+  return useContext(PrototypeSlugContext);
+}
+
+export function buildPrototypeTargetId(slug: string, id: string): string {
+  return `${slug}.${id}`;
+}
+
+export function getPrototypeTargetElement(
+  element: HTMLElement | null,
+): HTMLElement | null {
+  if (!element) return null;
+  const anchor = element.closest(`[${PROTOTYPE_TARGET_ATTR}]`);
+  return anchor instanceof HTMLElement ? anchor : null;
+}
+
+export function getPrototypeTargetIdFromElement(
+  element: HTMLElement | null,
+): string | null {
+  const anchor = getPrototypeTargetElement(element);
+  if (!anchor) return null;
+  return anchor.getAttribute(PROTOTYPE_TARGET_ATTR);
+}
+
+export type PrototypeTargetProps<T extends ElementType = "div"> = {
+  /** Registry segment id — must be listed in the prototype's component-ids.ts */
+  id: string;
+  label?: string;
+  as?: T;
+  className?: string;
+  children?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<T>, "as" | "id" | "children" | "className">;
+
+function defaultLabel(id: string): string {
+  return id
+    .split(".")
+    .map((part) => part.replace(/-/g, " "))
+    .join(" — ");
+}
+
+export function PrototypeTarget<T extends ElementType = "div">({
+  id,
+  label,
+  as,
+  className,
+  children,
+  ...rest
+}: PrototypeTargetProps<T>) {
+  const slug = usePrototypeSlug();
+  const componentRegistry = useContext(PrototypeRegistryContext);
+  const Component = (as ?? "div") as ElementType;
+  const fullId = slug ? buildPrototypeTargetId(slug, id) : id;
+  const displayLabel = label ?? defaultLabel(id);
+
+  if (
+    process.env.NODE_ENV !== "production" &&
+    componentRegistry &&
+    !isAllowedComponentTargetId(id, componentRegistry)
+  ) {
+    console.error(
+      `[PrototypeTarget] Unregistered id "${id}". Add it to the prototype component-ids registry.`,
+    );
+  }
+
+  return (
+    <Component
+      {...rest}
+      className={cn(className)}
+      {...{
+        [PROTOTYPE_TARGET_ATTR]: fullId,
+        "data-element": displayLabel,
+      }}
+    >
+      {children}
+    </Component>
+  );
+}
+
+/** Required root wrapper for every prototype UI component (see AGENTS.md). */
+export const PrototypeComponent = PrototypeTarget;

package/src/components/prototypes/prototype-tweak-highlight.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { injectCaptureColorTokens } from "@prototype/lib/prototype-comments/core/capture-theme";
+import { resolveAnnotationTargetById } from "@prototype/lib/prototype-comments/core/annotation-target";
+import styles from "@prototype/lib/prototype-comments/ui/capture-styles.module.scss";
+import { cn } from "@prototype/lib/utils";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+type HighlightRect = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+};
+
+type PrototypeTweakHighlightProps = {
+  targetId: string;
+  onComplete: () => void;
+};
+
+/** Fade in, hold, then fade out. */
+const HOLD_MS = 1500;
+const FADE_MS = 250;
+
+const HIGHLIGHT_BORDER =
+  "color-mix(in srgb, var(--prototype-comment-color-blue) 60%, transparent)";
+const HIGHLIGHT_FILL =
+  "color-mix(in srgb, var(--prototype-comment-color-blue) 5%, transparent)";
+
+function findTweakTarget(targetId: string): HTMLElement | null {
+  const byExact = resolveAnnotationTargetById(targetId);
+  if (byExact) return byExact;
+
+  const screenshotRoot = document.querySelector("[data-prototype-screenshot]");
+  return (
+    screenshotRoot?.querySelector<HTMLElement>(
+      `[data-prototype-target$=".${CSS.escape(targetId)}"]`,
+    ) ?? null
+  );
+}
+
+export function PrototypeTweakHighlight({
+  targetId,
+  onComplete,
+}: PrototypeTweakHighlightProps) {
+  const [mounted, setMounted] = useState(false);
+  const [rect, setRect] = useState<HighlightRect | null>(null);
+  const [isExiting, setIsExiting] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    injectCaptureColorTokens();
+  }, []);
+
+  useEffect(() => {
+    if (!mounted) return;
+
+    const updateRect = () => {
+      const element = findTweakTarget(targetId);
+      if (!element) {
+        setRect(null);
+        return;
+      }
+
+      const nextRect = element.getBoundingClientRect();
+      setRect({
+        top: nextRect.top,
+        left: nextRect.left,
+        width: nextRect.width,
+        height: nextRect.height,
+      });
+    };
+
+    updateRect();
+
+    const retryTimer = window.setInterval(updateRect, 50);
+    const stopRetryTimer = window.setTimeout(
+      () => window.clearInterval(retryTimer),
+      400,
+    );
+
+    const reducedMotion = window.matchMedia(
+      "(prefers-reduced-motion: reduce)",
+    ).matches;
+
+    const holdMs = reducedMotion ? 120 : HOLD_MS;
+    const fadeMs = reducedMotion ? 0 : FADE_MS;
+
+    const exitTimer = window.setTimeout(() => setIsExiting(true), holdMs + fadeMs);
+    const completeTimer = window.setTimeout(
+      onComplete,
+      holdMs + fadeMs * 2,
+    );
+
+    window.addEventListener("scroll", updateRect, true);
+    window.addEventListener("resize", updateRect);
+
+    return () => {
+      window.clearInterval(retryTimer);
+      window.clearTimeout(stopRetryTimer);
+      window.clearTimeout(exitTimer);
+      window.clearTimeout(completeTimer);
+      window.removeEventListener("scroll", updateRect, true);
+      window.removeEventListener("resize", updateRect);
+    };
+  }, [mounted, onComplete, targetId]);
+
+  if (!mounted || !rect) return null;
+
+  return createPortal(
+    <div
+      aria-hidden
+      data-prototype-comment-accent="blue"
+      className={cn(
+        styles.singleSelectOutline,
+        isExiting ? styles.exit : styles.enter,
+        "z-[1045] motion-reduce:transition-none",
+      )}
+      style={{
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+        borderColor: HIGHLIGHT_BORDER,
+        backgroundColor: HIGHLIGHT_FILL,
+        animationDuration: `${FADE_MS}ms`,
+      }}
+    />,
+    document.body,
+  );
+}

package/src/components/prototypes/prototype-tweaks.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import {
+  focusPrototypeTweak,
+  registerPrototypeTweaks,
+} from "@prototype/lib/prototypes/prototype-tweak-registry";
+import type { PrototypeTweakDefinition } from "@prototype/lib/prototypes/prototype-tweak-types";
+import { useLayoutEffect, useMemo, useRef } from "react";
+
+export type PrototypeTweakConfig = PrototypeTweakDefinition & {
+  onNavigate: () => void;
+};
+
+type PrototypeTweaksProps = {
+  tweaks: PrototypeTweakConfig[];
+};
+
+export function PrototypeTweaks({ tweaks }: PrototypeTweaksProps) {
+  const navigateRef = useRef<Map<string, () => void>>(new Map());
+
+  const items = useMemo(() => {
+    const nextNavigate = new Map<string, () => void>();
+    const nextItems = tweaks.map((tweak) => {
+      nextNavigate.set(tweak.id, tweak.onNavigate);
+      return {
+        id: tweak.id,
+        label: tweak.label,
+        targetId: tweak.targetId,
+        category: tweak.category,
+      };
+    });
+    navigateRef.current = nextNavigate;
+    return nextItems;
+  }, [tweaks]);
+
+  useLayoutEffect(() => {
+    registerPrototypeTweaks({
+      items,
+      navigateTo: (id) => {
+        navigateRef.current.get(id)?.();
+      },
+    });
+  }, [items]);
+
+  return null;
+}
+
+export { focusPrototypeTweak };