proto-plugin 0.1.0

package/src/lib/prototype-comments/react/CommentProvider.tsx

@@ -0,0 +1,298 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+import { captureInteractionState } from "../core/capture";
+import { getRepliesForParent } from "../core/comment-threads";
+import { commentToLiveState } from "../core/restore";
+import { normalizeAnnotationViewport } from "../core/normalize-viewport";
+import { createRemoteStorageAdapter } from "../core/storage";
+import type { CommentAnnotation, CommentStore } from "../core/types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CommentContext = createContext<CommentStore<any> | null>(null);
+
+type CommentProviderProps<TState> = {
+  children: ReactNode;
+  slug: string;
+  getLiveState: () => TState;
+  onRestore: (live: TState) => void;
+};
+
+export function CommentProvider<TState>({
+  children,
+  slug,
+  getLiveState,
+  onRestore,
+}: CommentProviderProps<TState>) {
+  const [annotations, setAnnotations] = useState<CommentAnnotation<TState>[]>([]);
+  const [storageReady, setStorageReady] = useState(false);
+  const [storageError, setStorageError] = useState<string | null>(null);
+
+  const getLiveStateRef = useRef(getLiveState);
+  const onRestoreRef = useRef(onRestore);
+  useEffect(() => { getLiveStateRef.current = getLiveState; }, [getLiveState]);
+  useEffect(() => { onRestoreRef.current = onRestore; }, [onRestore]);
+
+  const handleLoadError = useCallback((message: string) => {
+    setStorageError(message);
+  }, []);
+
+  const storage = useMemo(
+    () =>
+      createRemoteStorageAdapter<CommentAnnotation<TState>>(
+        slug,
+        undefined,
+        handleLoadError,
+      ),
+    [slug, handleLoadError],
+  );
+
+  const persistAnnotation = useCallback(
+    async (annotation: CommentAnnotation<TState>) => {
+      await storage.upsert(annotation);
+    },
+    [storage],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadAnnotations() {
+      setStorageReady(false);
+      setStorageError(null);
+
+      try {
+        const stored = await storage.load();
+        if (cancelled) return;
+        setAnnotations(stored);
+      } catch (error) {
+        if (cancelled) return;
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to load comments.";
+        setStorageError(message);
+        setAnnotations([]);
+      } finally {
+        if (!cancelled) setStorageReady(true);
+      }
+    }
+
+    void loadAnnotations();
+
+    const reloadFromRemote = () => {
+      if (document.visibilityState !== "visible") return;
+      void Promise.resolve(storage.load()).then((stored) => {
+        if (!cancelled) setAnnotations(stored);
+      }).catch(() => {
+        // Keep showing the current comments if a background refresh fails.
+      });
+    };
+
+    document.addEventListener("visibilitychange", reloadFromRemote);
+    window.addEventListener("focus", reloadFromRemote);
+
+    return () => {
+      cancelled = true;
+      document.removeEventListener("visibilitychange", reloadFromRemote);
+      window.removeEventListener("focus", reloadFromRemote);
+    };
+  }, [storage]);
+
+  const addAnnotation = useCallback(
+    (fields: Omit<CommentAnnotation<TState>, "interactionState">): CommentAnnotation<TState> => {
+      if (!storageReady || storageError) {
+        throw new Error(storageError ?? "Comments are still loading.");
+      }
+
+      const { captureViewport, viewportBoundingBox } = normalizeAnnotationViewport(fields);
+      const fullAnnotation: CommentAnnotation<TState> = {
+        ...fields,
+        captureViewport,
+        viewportBoundingBox,
+        interactionState: captureInteractionState(getLiveStateRef.current()),
+      };
+      setAnnotations((prev) => [...prev, fullAnnotation]);
+      void persistAnnotation(fullAnnotation).catch(() => {
+        // errors are reported via onError in the remote adapter
+      });
+      return fullAnnotation;
+    },
+    [storageReady, storageError, persistAnnotation],
+  );
+
+  const addReply = useCallback(
+    (parentId: string, comment: string): CommentAnnotation<TState> => {
+      if (!storageReady || storageError) {
+        throw new Error(storageError ?? "Comments are still loading.");
+      }
+
+      const parent = annotations.find((a) => a.id === parentId && !a.deleted);
+      if (!parent) {
+        throw new Error("Parent comment not found.");
+      }
+
+      const trimmed = comment.trim();
+      if (!trimmed) {
+        throw new Error("Reply cannot be empty.");
+      }
+
+      const reply: CommentAnnotation<TState> = {
+        id: `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+        parentId: parent.id,
+        comment: trimmed,
+        timestamp: Date.now(),
+        x: parent.x,
+        y: parent.y,
+        element: parent.element,
+        elementPath: parent.elementPath,
+        targetId: parent.targetId,
+        positionAnchor: parent.positionAnchor,
+        interactionState: parent.interactionState,
+        channel: parent.channel,
+      };
+
+      setAnnotations((prev) => [...prev, reply]);
+      void persistAnnotation(reply).catch(() => {});
+      return reply;
+    },
+    [annotations, storageReady, storageError, persistAnnotation],
+  );
+
+  const updateAnnotation = useCallback(
+    (id: string, comment: string) => {
+      let nextAnnotation: CommentAnnotation<TState> | undefined;
+      setAnnotations((prev) => {
+        const current = prev.find((a) => a.id === id);
+        if (!current) return prev;
+        nextAnnotation = { ...current, comment };
+        return prev.map((a) => (a.id === id ? nextAnnotation! : a));
+      });
+      if (nextAnnotation) {
+        void persistAnnotation(nextAnnotation).catch(() => {});
+      }
+    },
+    [persistAnnotation],
+  );
+
+  const resolveAnnotation = useCallback(
+    (id: string) => {
+      let nextAnnotation: CommentAnnotation<TState> | undefined;
+      setAnnotations((prev) => {
+        const current = prev.find((a) => a.id === id);
+        if (!current) return prev;
+        nextAnnotation = {
+          ...current,
+          status: current.status === "resolved" ? "pending" : "resolved",
+        };
+        return prev.map((a) => (a.id === id ? nextAnnotation! : a));
+      });
+      if (nextAnnotation) {
+        void persistAnnotation(nextAnnotation).catch(() => {});
+      }
+    },
+    [persistAnnotation],
+  );
+
+  const deleteAnnotation = useCallback(
+    (id: string) => {
+      let toDelete: CommentAnnotation<TState>[] = [];
+      setAnnotations((prev) => {
+        const target = prev.find((a) => a.id === id);
+        if (!target) return prev;
+        const replyIds = new Set(
+          getRepliesForParent(prev, id).map((reply) => reply.id),
+        );
+        toDelete = [
+          target,
+          ...prev.filter((a) => replyIds.has(a.id)),
+        ];
+        const removeIds = new Set([id, ...replyIds]);
+        return prev.filter((a) => !removeIds.has(a.id));
+      });
+      for (const annotation of toDelete) {
+        void persistAnnotation({ ...annotation, deleted: true }).catch(() => {});
+      }
+    },
+    [persistAnnotation],
+  );
+
+  const clearAllAnnotations = useCallback(() => {
+    let visible: CommentAnnotation<TState>[] = [];
+    setAnnotations((prev) => {
+      visible = prev;
+      return [];
+    });
+    for (const annotation of visible) {
+      void persistAnnotation({ ...annotation, deleted: true }).catch(() => {});
+    }
+  }, [persistAnnotation]);
+
+  const restoreComment = useCallback(
+    (id: string): CommentAnnotation<TState> | undefined => {
+      const annotation = annotations.find((a) => a.id === id);
+      if (!annotation) return undefined;
+      const live = commentToLiveState(annotation.interactionState);
+      onRestoreRef.current(live);
+      return annotation;
+    },
+    [annotations],
+  );
+
+  const value = useMemo(
+    (): CommentStore<TState> => ({
+      slug,
+      annotations,
+      storageReady,
+      storageError,
+      addAnnotation,
+      addReply,
+      updateAnnotation,
+      resolveAnnotation,
+      deleteAnnotation,
+      clearAllAnnotations,
+      restoreComment,
+    }),
+    [
+      slug,
+      annotations,
+      storageReady,
+      storageError,
+      addAnnotation,
+      addReply,
+      updateAnnotation,
+      resolveAnnotation,
+      deleteAnnotation,
+      clearAllAnnotations,
+      restoreComment,
+    ],
+  );
+
+  return (
+    <CommentContext.Provider value={value}>
+      {children}
+    </CommentContext.Provider>
+  );
+}
+
+export function useCommentStore<TState>(): CommentStore<TState> {
+  const context = useContext(CommentContext);
+  if (!context) {
+    throw new Error("useCommentStore must be used within CommentProvider");
+  }
+  return context as CommentStore<TState>;
+}
+
+export function useCommentStoreOptional<TState>(): CommentStore<TState> | null {
+  return useContext(CommentContext) as CommentStore<TState> | null;
+}

package/src/lib/prototype-comments/scss.d.ts

@@ -0,0 +1,10 @@
+// Type declarations for SCSS modules
+declare module "*.module.scss" {
+  const classes: { [key: string]: string };
+  export default classes;
+}
+
+declare module "*.scss" {
+  const content: { [key: string]: string };
+  export default content;
+}

package/src/lib/prototype-comments/ui/CommentAnnotationOverlay.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { createPortal } from "react-dom";
+
+import {
+  getAnnotationMarkerPosition,
+  getAnnotationOutlineBox,
+  getMarkerViewportPosition,
+  getPrototypeScrollContainer,
+  resolveAnnotationTargetById,
+  resolveAnnotationTargetElement,
+  type AnnotationTargetOptions,
+} from "../core/annotation-target";
+import {
+  resolveThreadRootId,
+} from "../core/comment-threads";
+import { parseComputedStylesString } from "../core/element-identification";
+import type { CommentAnnotation } from "../core/types";
+import { useLayoutShift } from "../hooks/useLayoutShift";
+import { useCommentStore } from "../react/CommentProvider";
+import { usePrototypeToolTheme } from "@prototype/lib/prototypes/use-prototype-tool-theme";
+import { AnnotationPopupCSS } from "./annotation-popup";
+import { AnnotationMarker } from "./annotation-marker";
+import styles from "./capture-styles.module.scss";
+
+type CommentAnnotationOverlayProps<TState = unknown> = {
+  annotation: CommentAnnotation<TState>;
+  basePath?: string;
+  onDismiss?: () => void;
+  readOnly?: boolean;
+  resolveTargetOptions?: AnnotationTargetOptions;
+};
+
+export function CommentAnnotationOverlay<TState = unknown>({
+  annotation,
+  basePath = "/canvas",
+  onDismiss,
+  readOnly = false,
+  resolveTargetOptions,
+}: CommentAnnotationOverlayProps<TState>) {
+  const router = useRouter();
+  const { annotations, updateAnnotation, deleteAnnotation } =
+    useCommentStore<TState>();
+  const { useLightTheme, commentTheme } = usePrototypeToolTheme();
+  const [mounted, setMounted] = useState(false);
+  const [ready, setReady] = useState(false);
+  const [scrollY, setScrollY] = useState(0);
+  const [targetElement, setTargetElement] = useState<HTMLElement | null>(null);
+  const [isExiting, setIsExiting] = useState(false);
+  const layoutVersion = useLayoutShift();
+
+  useEffect(() => {
+    setMounted(true);
+    setScrollY(window.scrollY);
+
+    const frame = requestAnimationFrame(() => {
+      setReady(true);
+    });
+
+    return () => cancelAnimationFrame(frame);
+  }, []);
+
+  const rootId = resolveThreadRootId(annotations, annotation.id);
+  const rootAnnotation = useMemo(
+    () => annotations.find((item) => item.id === rootId) ?? annotation,
+    [annotations, rootId, annotation],
+  );
+
+  const refreshTarget = useCallback(() => {
+    setScrollY(window.scrollY);
+    setTargetElement(
+      resolveAnnotationTargetElement(
+        rootAnnotation,
+        window.scrollY,
+        resolveTargetOptions,
+      ),
+    );
+  }, [rootAnnotation, resolveTargetOptions]);
+
+  useEffect(() => {
+    if (!ready) return;
+
+    refreshTarget();
+
+    const handleScroll = () => refreshTarget();
+    const handleResize = () => refreshTarget();
+
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    window.addEventListener("resize", handleResize);
+
+    const scrollContainer = getPrototypeScrollContainer();
+    scrollContainer?.addEventListener("scroll", handleScroll, { passive: true });
+
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+      window.removeEventListener("resize", handleResize);
+      scrollContainer?.removeEventListener("scroll", handleScroll);
+    };
+  }, [ready, refreshTarget, layoutVersion]);
+
+  const navigateAway = useCallback(() => {
+    setIsExiting(true);
+    window.setTimeout(() => {
+      if (onDismiss) {
+        onDismiss();
+      } else {
+        router.push(basePath);
+      }
+    }, 150);
+  }, [router, basePath, onDismiss]);
+
+  const handleSave = useCallback(
+    (comment: string) => {
+      updateAnnotation(rootAnnotation.id, comment);
+    },
+    [rootAnnotation.id, updateAnnotation],
+  );
+
+  const handleDelete = useCallback(() => {
+    deleteAnnotation(rootAnnotation.id);
+    navigateAway();
+  }, [rootAnnotation.id, deleteAnnotation, navigateAway]);
+
+  if (!mounted || !ready) {
+    return null;
+  }
+
+  const targetMissing =
+    Boolean(rootAnnotation.targetId) &&
+    !targetElement &&
+    !resolveAnnotationTargetById(rootAnnotation.targetId!);
+
+  const outlineBox = getAnnotationOutlineBox(rootAnnotation, targetElement, scrollY);
+  const positionStyle = getAnnotationMarkerPosition(rootAnnotation, targetElement, scrollY);
+  const markerViewport = getMarkerViewportPosition(rootAnnotation, scrollY, targetElement);
+  const popupLeft = Math.max(160, Math.min(window.innerWidth - 160, markerViewport.x));
+  const popupPosition =
+    markerViewport.y > window.innerHeight - 290
+      ? { bottom: window.innerHeight - markerViewport.y + 20 }
+      : { top: markerViewport.y + 20 };
+
+  const markerLayerClassName = rootAnnotation.isFixed
+    ? styles.fixedMarkersLayer
+    : styles.markersLayer;
+
+  return createPortal(
+    (
+      <div
+        className={styles.captureScope}
+        data-prototype-comment-theme={commentTheme}
+        data-prototype-comment-accent="blue"
+        data-prototype-comment-root=""
+      >
+        {!readOnly && (
+          <div className={markerLayerClassName} style={{ zIndex: 99999 }}>
+            <AnnotationMarker
+              annotation={{
+                ...rootAnnotation,
+                status: rootAnnotation.status ?? "pending",
+              }}
+              globalIndex={0}
+              layerIndex={0}
+              layerSize={1}
+              isExiting={false}
+              isClearing={false}
+              isAnimated
+              isHovered={false}
+              isDeleting={false}
+              isEditingAny
+              renumberFrom={null}
+              markerClickBehavior="edit"
+              positionStyle={positionStyle}
+              onHoverEnter={() => {}}
+              onHoverLeave={() => {}}
+              onClick={() => {}}
+            />
+          </div>
+        )}
+
+        {outlineBox ? (
+          <div
+            className={styles.targetHighlightLayer}
+            data-comment-target-highlight=""
+          >
+            <div
+              className={`${rootAnnotation.isMultiSelect ? styles.multiSelectOutline : styles.singleSelectOutline} ${styles.enter}`}
+              style={{
+                left: outlineBox.x,
+                top: outlineBox.y,
+                width: outlineBox.width,
+                height: outlineBox.height,
+                ...(rootAnnotation.isMultiSelect
+                  ? {}
+                  : {
+                      borderColor:
+                        "color-mix(in srgb, var(--prototype-comment-color-accent) 60%, transparent)",
+                      backgroundColor:
+                        "color-mix(in srgb, var(--prototype-comment-color-accent) 5%, transparent)",
+                    }),
+              }}
+            />
+          </div>
+        ) : null}
+
+        <div className={styles.overlay} style={{ zIndex: 99999 }}>
+          {targetMissing && (
+            <div
+              className={styles.targetUnresolvedBanner}
+              style={{
+                position: "fixed",
+                top: 12,
+                left: "50%",
+                transform: "translateX(-50%)",
+                zIndex: 100000,
+              }}
+            >
+              Original target not found — position may be approximate
+            </div>
+          )}
+
+          <AnnotationPopupCSS
+            element={rootAnnotation.element}
+            selectedText={rootAnnotation.selectedText}
+            computedStyles={parseComputedStylesString(
+              rootAnnotation.computedStyles,
+            )}
+            placeholder="Edit your feedback..."
+            initialValue={rootAnnotation.comment}
+            submitLabel="Save"
+            readOnly={readOnly}
+            onSubmit={handleSave}
+            onCancel={navigateAway}
+            onDelete={readOnly ? undefined : handleDelete}
+            isExiting={isExiting}
+            lightMode={useLightTheme}
+            accentColor={
+              rootAnnotation.isMultiSelect
+                ? "var(--prototype-comment-color-green)"
+                : "var(--prototype-comment-color-accent)"
+            }
+            style={{
+              left: popupLeft,
+              ...popupPosition,
+            }}
+          />
+        </div>
+      </div>
+    ) as any,
+    document.body,
+  );
+}

package/src/lib/prototype-comments/ui/CommentDetailPage.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useLayoutEffect, useMemo, type ReactNode } from "react";
+
+import { useCommentStore } from "../react/CommentProvider";
+
+type CommentDetailPageProps<TState> = {
+  id: string;
+  basePath?: string;
+  renderRestoredView: (props: { route: string }) => ReactNode;
+  renderNotFound?: (props: { basePath: string }) => ReactNode;
+};
+
+export function CommentDetailPage<TState>({
+  id,
+  basePath = "/canvas",
+  renderRestoredView,
+  renderNotFound,
+}: CommentDetailPageProps<TState>) {
+  const { annotations, restoreComment } = useCommentStore<TState>();
+
+  const annotation = useMemo(
+    () => annotations.find((item) => item.id === id),
+    [annotations, id]
+  );
+
+  useLayoutEffect(() => {
+    if (annotation) {
+      restoreComment(annotation.id);
+    }
+  }, [annotation, restoreComment]);
+
+  if (!annotation) {
+    if (renderNotFound) {
+      return <>{renderNotFound({ basePath })}</>;
+    }
+
+    return (
+      <div style={{ padding: "40px 24px", textAlign: "center", color: "rgba(255,255,255,0.5)" }}>
+        <p style={{ margin: 0, fontSize: "14px" }}>No comment exists with this id.</p>
+        <a
+          href={basePath}
+          style={{
+            display: "inline-block",
+            marginTop: "16px",
+            fontSize: "14px",
+            color: "rgba(255,255,255,0.8)",
+          }}>
+          Back to canvas
+        </a>
+      </div>
+    );
+  }
+
+  return <>{renderRestoredView({ route: annotation.interactionState.route })}</>;
+}

package/src/lib/prototype-comments/ui/CommentHeaderCount.tsx

@@ -0,0 +1,28 @@
+import { cn } from "@prototype/lib/utils";
+
+type CommentHeaderCountProps = {
+  unresolved: number;
+  total: number;
+  className?: string;
+};
+
+export function CommentHeaderCount({
+  unresolved,
+  total,
+  className,
+}: CommentHeaderCountProps) {
+  if (total === 0) return null;
+
+  const base = cn("ml-1.5 tabular-nums", className);
+
+  if (unresolved === total) {
+    return <span className={cn(base, "text-foreground")}>{total}</span>;
+  }
+
+  return (
+    <span className={cn(base, "text-foreground")}>
+      {unresolved}
+      <span className="text-muted-foreground"> / {total}</span>
+    </span>
+  );
+}