proto-plugin 0.1.0

package/src/lib/prototype-comments/core/storage.ts

@@ -0,0 +1,80 @@
+import { isValidAnnotation } from "./validation";
+
+export interface CommentStorageAdapter<T extends { id: string }> {
+  load(): T[] | Promise<T[]>;
+  upsert(annotation: T): Promise<void>;
+}
+
+export class CommentStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CommentStorageError";
+  }
+}
+
+export function createRemoteStorageAdapter<T extends { id: string }>(
+  slug: string,
+  validate: (value: unknown) => boolean = isValidAnnotation,
+  onError?: (message: string) => void,
+): CommentStorageAdapter<T> {
+  const listUrl = `/api/prototypes/${encodeURIComponent(slug)}/comments`;
+
+  async function requestUpsert(annotation: T): Promise<void> {
+    const response = await fetch(
+      `${listUrl}/${encodeURIComponent(annotation.id)}`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(annotation),
+      },
+    );
+
+    if (response.status === 503) {
+      throw new CommentStorageError(
+        "Comment 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 CommentStorageError(body?.error ?? "Failed to save comment.");
+    }
+  }
+
+  return {
+    async load(): Promise<T[]> {
+      const response = await fetch(listUrl);
+
+      if (response.status === 503) {
+        throw new CommentStorageError(
+          "Comment 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 CommentStorageError(body?.error ?? "Failed to load comments.");
+      }
+
+      const parsed: unknown = await response.json();
+      if (!Array.isArray(parsed)) return [];
+      return (parsed as unknown[]).filter(validate) as T[];
+    },
+
+    async upsert(annotation: T): Promise<void> {
+      try {
+        await requestUpsert(annotation);
+      } catch (error) {
+        console.error(
+          "[prototype-comments] Failed to save comment:",
+          error instanceof Error ? error.message : error,
+        );
+        throw error;
+      }
+    },
+  };
+}

package/src/lib/prototype-comments/core/types.ts

@@ -0,0 +1,79 @@
+export type AnnotationBoundingBox = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type CaptureViewport = {
+  width: number;
+  height: number;
+  scrollY: number;
+  /** Scroll offset of the prototype content container (not window) */
+  scrollTop?: number;
+};
+
+export type CommentAnnotationFields = {
+  id: string;
+  x: number;
+  y: number;
+  comment: string;
+  element: string;
+  elementPath: string;
+  timestamp: number;
+  selectedText?: string;
+  boundingBox?: AnnotationBoundingBox;
+  /** Element bounds in viewport coordinates at screenshot capture time */
+  viewportBoundingBox?: AnnotationBoundingBox;
+  /** Viewport dimensions when the screenshot was taken */
+  captureViewport?: CaptureViewport;
+  positionAnchor?: "viewport" | "element";
+  /** Full id from data-prototype-target, e.g. my-slug.filter-bar.status */
+  targetId?: string;
+  nearbyText?: string;
+  cssClasses?: string;
+  isMultiSelect?: boolean;
+  isFixed?: boolean;
+  fullPath?: string;
+  accessibility?: string;
+  computedStyles?: string;
+  nearbyElements?: string;
+  reactComponents?: string;
+  sourceFile?: string;
+  sessionId?: string;
+  url?: string;
+  status?: "pending" | "acknowledged" | "resolved" | "dismissed";
+  /** When set, this annotation is a reply on the root comment with this id. */
+  parentId?: string;
+  /** Soft-delete flag — deleted comments stay in storage but are hidden in UI. */
+  deleted?: boolean;
+  /** Review comments vs change log notes. Defaults to `"comment"`. */
+  channel?: "comment" | "changelog";
+};
+
+/** The stored interaction state: prototype live state + package-added metadata */
+export type CommentInteractionState<TState> = TState & {
+  capturedAt: string;
+  route: string;
+};
+
+export type CommentAnnotation<TState> = CommentAnnotationFields & {
+  interactionState: CommentInteractionState<TState>;
+  screenshot?: string;
+};
+
+export type CommentStore<TState> = {
+  slug: string;
+  annotations: CommentAnnotation<TState>[];
+  storageReady: boolean;
+  storageError: string | null;
+  addAnnotation: (
+    fields: Omit<CommentAnnotation<TState>, "interactionState">,
+  ) => CommentAnnotation<TState>;
+  addReply: (parentId: string, comment: string) => CommentAnnotation<TState>;
+  updateAnnotation: (id: string, comment: string) => void;
+  resolveAnnotation: (id: string) => void;
+  deleteAnnotation: (id: string) => void;
+  clearAllAnnotations: () => void;
+  restoreComment: (id: string) => CommentAnnotation<TState> | undefined;
+};

package/src/lib/prototype-comments/core/validation.ts

@@ -0,0 +1,17 @@
+export function isValidAnnotation(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const a = value as Record<string, unknown>;
+  return (
+    typeof a.id === "string" &&
+    typeof a.comment === "string" &&
+    typeof a.timestamp === "number" &&
+    a.interactionState != null &&
+    typeof (a.interactionState as Record<string, unknown>).capturedAt ===
+      "string" &&
+    (a.deleted === undefined || typeof a.deleted === "boolean") &&
+    (a.parentId === undefined || typeof a.parentId === "string") &&
+    (a.channel === undefined ||
+      a.channel === "comment" ||
+      a.channel === "changelog")
+  );
+}

package/src/lib/prototype-comments/hooks/useLayoutShift.ts

@@ -0,0 +1,61 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Increments a counter whenever page layout shifts in ways that don't fire
+ * window resize — e.g. comments sidebar open/close animating body margin.
+ */
+export function useLayoutShift(): number {
+  const [layoutVersion, setLayoutVersion] = useState(0);
+
+  useEffect(() => {
+    const bump = () => setLayoutVersion((v) => v + 1);
+
+    const resizeObserver = new ResizeObserver(bump);
+    resizeObserver.observe(document.body);
+
+    const mutationObserver = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (
+          mutation.type === "attributes" &&
+          mutation.attributeName === "data-comments-sidebar-open"
+        ) {
+          bump();
+          break;
+        }
+      }
+    });
+    mutationObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-comments-sidebar-open", "data-comments-sidebar-resizing", "style"],
+    });
+
+    const handleTransitionEnd = (event: TransitionEvent) => {
+      const target = event.target;
+      if (!(target instanceof HTMLElement)) return;
+
+      if (
+        target === document.body &&
+        event.propertyName === "margin-right"
+      ) {
+        bump();
+        return;
+      }
+
+      if (
+        target.id === "prototype-comments-sidebar-root" &&
+        event.propertyName === "width"
+      ) {
+        bump();
+      }
+    };
+    document.body.addEventListener("transitionend", handleTransitionEnd);
+
+    return () => {
+      resizeObserver.disconnect();
+      mutationObserver.disconnect();
+      document.body.removeEventListener("transitionend", handleTransitionEnd);
+    };
+  }, []);
+
+  return layoutVersion;
+}

package/src/lib/prototype-comments/index.ts

@@ -0,0 +1,58 @@
+// Core utilities (no React)
+export { captureInteractionState } from "./core/capture";
+export { commentToLiveState } from "./core/restore";
+export { createRemoteStorageAdapter, CommentStorageError } from "./core/storage";
+export type { CommentStorageAdapter } from "./core/storage";
+export { isValidAnnotation } from "./core/validation";
+export {
+  getRepliesForParent,
+  getRootAnnotations,
+  isRootAnnotation,
+  resolveThreadRootId,
+} from "./core/comment-threads";
+export { normalizeAnnotationViewport } from "./core/normalize-viewport";
+export { formatAnnotationWithState, formatAllAnnotations } from "./core/export";
+export { captureViewportScreenshot } from "./core/screenshot";
+export {
+  closestCrossingShadow,
+  identifyElement,
+  parseComputedStylesString,
+} from "./core/element-identification";
+export {
+  resolveAnnotationTargetElement,
+  resolveAnnotationTargetById,
+  getPrototypeScrollContainer,
+  getAnnotationMarkerPosition,
+  getAnnotationOutlineBox,
+  getMarkerViewportPosition,
+  PROTOTYPE_TARGET_ATTR,
+  type AnnotationTargetOptions,
+} from "./core/annotation-target";
+
+// Types
+export type {
+  AnnotationBoundingBox,
+  CaptureViewport,
+  CommentAnnotationFields,
+  CommentInteractionState,
+  CommentAnnotation,
+  CommentStore,
+} from "./core/types";
+
+// React
+export {
+  CommentProvider,
+  useCommentStore,
+  useCommentStoreOptional,
+} from "./react/CommentProvider";
+export { CommentCaptureToolbar } from "./react/CommentCaptureToolbar";
+export type { CommentCaptureToolbarProps } from "./react/CommentCaptureToolbar";
+
+// UI
+export { getViewportBoundingBox, getCaptureAspectRatio } from "./ui/comment-highlight";
+export { isCanvasDetailPath, isCanvasPath } from "./ui/is-comment-detail-path";
+export { CommentsGrid } from "./ui/CommentsGrid";
+export { CommentsListPage } from "./ui/CommentsListPage";
+export { CommentDetailPage } from "./ui/CommentDetailPage";
+export { CommentsSidebar } from "./ui/CommentsSidebar";
+export { CommentAnnotationOverlay } from "./ui/CommentAnnotationOverlay";