proto-plugin 0.1.0

package/src/lib/pr-split/build-pr-agent-prompt.ts

@@ -0,0 +1,68 @@
+import { buildPrSplitPrototypeUrl } from "./build-pr-split-prototype-url";
+import type {
+  PrSplitAgentPromptConfig,
+  PrSplitConfig,
+  PrSplitEntry,
+} from "./pr-split-types";
+
+export function buildPrAgentPrompt<TLiveState>(
+  entry: PrSplitEntry<string, TLiveState>,
+  allEntries: PrSplitEntry<string, TLiveState>[],
+  config: PrSplitConfig<TLiveState>,
+  origin = "http://localhost:3003",
+): string {
+  const priorPrs = allEntries.filter((e) => e.order < entry.order);
+  const prototypeUrl = buildPrSplitPrototypeUrl(entry, config, origin);
+  const lines = [
+    `Create a focused pull request in ${config.sourceRepo} for ${config.seriesLabel} #${entry.order}: ${entry.title}.`,
+    "",
+    "## Summary",
+    entry.description,
+    "",
+    "## Scope",
+    `- Estimated size: ${entry.size}`,
+    `- Primary UI target: \`${entry.targetId}\``,
+    `- Prototype preview: ${prototypeUrl}`,
+    "",
+  ];
+
+  if (priorPrs.length > 0) {
+    lines.push("## Depends on (merge order)");
+    for (const prior of priorPrs) {
+      const status = prior.prUrl
+        ? `${prior.prUrl}${prior.branch ? ` (branch: ${prior.branch})` : ""}`
+        : "not yet open";
+      lines.push(`- PR ${prior.order} · ${prior.title} — ${status}`);
+    }
+    lines.push("");
+  }
+
+  if (entry.analyticsNotes?.length) {
+    lines.push("## Event logging");
+    entry.analyticsNotes.forEach((note, index) => {
+      lines.push(`${index + 1}. ${note}`);
+    });
+    lines.push("");
+  }
+
+  const scopeGuardrail =
+    config.scopeNote ??
+    "Do not bundle unrelated work from other PR slices in this series.";
+
+  lines.push(
+    "## Instructions",
+    `1. Work in \`${config.sourceWorkPath}\` — find the target page and replicate this slice from the prototype with exact visual fidelity.`,
+    `2. Keep the PR small: only the changes described above. ${scopeGuardrail}`,
+    "3. Match prototype layout, spacing, semantic tokens, and interactive behavior.",
+    `4. Branch naming: \`${config.branchName(entry)}\`.`,
+    `5. After opening the pull request, copy the GitHub PR URL and add it to the matching card in \`${config.configFilePath}\` — set \`prUrl\` and \`branch\` on the matching \`PR_SPLIT_ENTRIES\` item so the prototype sidebar links to it.`,
+  );
+
+  if (entry.analyticsNotes?.length) {
+    lines.push("6. Add analytics events listed under Event logging.");
+  }
+
+  return lines.join("\n");
+}
+
+export type { PrSplitAgentPromptConfig };

package/src/lib/pr-split/build-pr-split-prototype-url.ts

@@ -0,0 +1,12 @@
+import type { PrSplitEntry, PrSplitUrlConfig } from "./pr-split-types";
+
+export function buildPrSplitPrototypeUrl<TLiveState>(
+  entry: PrSplitEntry<string, TLiveState>,
+  config: PrSplitUrlConfig<TLiveState>,
+  origin = "http://localhost:3003",
+): string {
+  const url = new URL(`/prototypes/${config.slug}`, origin);
+  config.writeEntryToSearchParams(url.searchParams, entry);
+  url.searchParams.set("prSplit", String(entry.order));
+  return url.toString();
+}

package/src/lib/pr-split/pr-split-highlight.ts

@@ -0,0 +1,6 @@
+/** Blue matches prototype comment accent tokens. */
+export const PR_TARGET_HIGHLIGHT_BORDER =
+  "color-mix(in srgb, var(--prototype-comment-color-blue) 55%, transparent)";
+
+export const PR_TARGET_HIGHLIGHT_FILL =
+  "color-mix(in srgb, var(--prototype-comment-color-blue) 6%, transparent)";

package/src/lib/pr-split/pr-split-types.ts

@@ -0,0 +1,58 @@
+export type PrSplitEntrySize = "Small" | "Medium" | "Large";
+
+export type PrSplitEntry<
+  TWireframeId extends string = string,
+  TLiveState = unknown,
+> = {
+  order: number;
+  title: string;
+  description: string;
+  size: PrSplitEntrySize;
+  targetId: string;
+  liveState: TLiveState;
+  wireframeId: TWireframeId;
+  prUrl?: string;
+  branch?: string;
+  /** Linear issue URL for this PR slice. */
+  linearUrl?: string;
+  /** Path appended to the Vercel preview host (e.g. demo list page). */
+  previewPath?: string;
+  /** Cached Vercel preview host when GitHub lookup is unavailable. */
+  vercelPreviewHost?: string;
+  analyticsNotes?: string[];
+  approved?: boolean;
+  merged?: boolean;
+};
+
+export type PrSplitAgentPromptConfig = {
+  /** Label for the PR series, e.g. "Feature area FE". */
+  seriesLabel: string;
+  /** GitHub repo slug where agents open PRs, e.g. "acme/source-app". */
+  sourceRepo: string;
+  /** Path within sourceRepo where agents implement the change, e.g. "apps/web". */
+  sourceWorkPath: string;
+  /** Path to the prototype's pr-split config file agents update after opening a PR. */
+  configFilePath: string;
+  /** Returns the full branch name for an entry. */
+  branchName: (entry: Pick<PrSplitEntry, "order" | "title">) => string;
+  /** Optional scope guardrail appended to default instructions. */
+  scopeNote?: string;
+};
+
+export type PrSplitUrlConfig<TLiveState = unknown> = {
+  /** Prototype slug — used in `/prototypes/[slug]`. */
+  slug: string;
+  /** Writes entry live state into search params (before `prSplit` is set). */
+  writeEntryToSearchParams: (
+    searchParams: URLSearchParams,
+    entry: PrSplitEntry<string, TLiveState>,
+  ) => void;
+};
+
+export type PrSplitConfig<TLiveState = unknown> = PrSplitAgentPromptConfig &
+  PrSplitUrlConfig<TLiveState> & {
+    /** Vercel project name to prefer when resolving preview URLs. */
+    vercelProjectName: string;
+    /** Default preview path when entry.previewPath is omitted. */
+    defaultPreviewPath: string;
+  };

package/src/lib/pr-split/resolve-source-preview-url.ts

@@ -0,0 +1,45 @@
+import type { VercelPreviewFromPr } from "../vercel-preview/parse-vercel-github-comment";
+import { buildVercelPreviewPageUrl } from "../vercel-preview/parse-vercel-github-comment";
+import type { PrSplitEntry } from "./pr-split-types";
+
+export function resolveSourcePreviewUrl<TLiveState>(
+  payload: VercelPreviewFromPr | null,
+  entry: Pick<
+    PrSplitEntry<string, TLiveState>,
+    "previewPath" | "vercelPreviewHost"
+  >,
+  options: {
+    defaultPreviewPath: string;
+    vercelProjectName: string;
+  },
+): { previewUrl: string; inspectorUrl: string | null } | null {
+  const previewPath = entry.previewPath ?? options.defaultPreviewPath;
+
+  if (payload) {
+    const sourceProject =
+      payload.projects.find(
+        (project) => project.name === options.vercelProjectName,
+      ) ?? payload.projects[0];
+    if (sourceProject?.previewUrl) {
+      return {
+        previewUrl: buildVercelPreviewPageUrl(
+          sourceProject.previewUrl,
+          previewPath,
+        ),
+        inspectorUrl: sourceProject.inspectorUrl ?? null,
+      };
+    }
+  }
+
+  if (entry.vercelPreviewHost) {
+    return {
+      previewUrl: buildVercelPreviewPageUrl(
+        entry.vercelPreviewHost,
+        previewPath,
+      ),
+      inspectorUrl: null,
+    };
+  }
+
+  return null;
+}

package/src/lib/pr-split/use-pr-vercel-previews.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+import type { VercelPreviewFromPr } from "../vercel-preview/parse-vercel-github-comment";
+
+const DEFAULT_PREVIEW_API_PATH = "/api/pr-vercel-preview";
+
+export function usePrVercelPreviews(
+  prUrls: string[],
+  previewApiPath = DEFAULT_PREVIEW_API_PATH,
+) {
+  const [previewCache, setPreviewCache] = useState(
+    () => new Map<string, VercelPreviewFromPr>(),
+  );
+  const [previewLoading, setPreviewLoading] = useState(false);
+
+  const prUrlsKey = useMemo(() => prUrls.join(","), [prUrls]);
+
+  useEffect(() => {
+    if (prUrls.length === 0) return;
+
+    let cancelled = false;
+    setPreviewLoading(true);
+
+    const params = new URLSearchParams({
+      prUrls: prUrls.join(","),
+    });
+
+    fetch(`${previewApiPath}?${params.toString()}`)
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error("Failed to fetch Vercel previews.");
+        }
+        return response.json() as Promise<{
+          previews: Array<{
+            prUrl: string;
+            preview: VercelPreviewFromPr | null;
+          }>;
+        }>;
+      })
+      .then((data) => {
+        if (cancelled) return;
+        const next = new Map<string, VercelPreviewFromPr>();
+        for (const item of data.previews) {
+          if (item.preview) {
+            next.set(item.prUrl, item.preview);
+          }
+        }
+        setPreviewCache(next);
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setPreviewCache(new Map());
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setPreviewLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [prUrlsKey, previewApiPath, prUrls.length]);
+
+  return { previewCache, previewLoading };
+}

package/src/lib/prototype-comments/core/annotation-channel.ts

@@ -0,0 +1,41 @@
+import type { CommentAnnotationFields } from "./types";
+import { getRootAnnotations } from "./comment-threads";
+
+export type AnnotationChannel = "comment" | "changelog";
+
+export function normalizeAnnotationChannel(
+  channel: CommentAnnotationFields["channel"] | undefined,
+): AnnotationChannel {
+  return channel === "changelog" ? "changelog" : "comment";
+}
+
+export function isChangelogAnnotation(
+  annotation: Pick<CommentAnnotationFields, "channel">,
+): boolean {
+  return normalizeAnnotationChannel(annotation.channel) === "changelog";
+}
+
+export function isCommentChannelAnnotation(
+  annotation: Pick<CommentAnnotationFields, "channel">,
+): boolean {
+  return !isChangelogAnnotation(annotation);
+}
+
+export function filterAnnotationsByChannel<T extends CommentAnnotationFields>(
+  annotations: readonly T[],
+  channel: AnnotationChannel,
+): T[] {
+  return annotations.filter((a) => normalizeAnnotationChannel(a.channel) === channel);
+}
+
+export function getChangelogRootAnnotations<T extends CommentAnnotationFields>(
+  annotations: readonly T[],
+): T[] {
+  return getRootAnnotations(filterAnnotationsByChannel(annotations, "changelog"));
+}
+
+export function getCommentRootAnnotations<T extends CommentAnnotationFields>(
+  annotations: readonly T[],
+): T[] {
+  return getRootAnnotations(filterAnnotationsByChannel(annotations, "comment"));
+}

package/src/lib/prototype-comments/core/annotation-status.ts

@@ -0,0 +1,60 @@
+import { isRootAnnotation } from "./comment-threads";
+import type { CommentAnnotationFields } from "./types";
+
+export function isAnnotationDeleted(
+  annotation: Pick<CommentAnnotationFields, "deleted">,
+): boolean {
+  return annotation.deleted === true;
+}
+
+export function isAnnotationResolved(
+  annotation: Pick<CommentAnnotationFields, "status">,
+): boolean {
+  return annotation.status === "resolved";
+}
+
+export function isVisibleAnnotation(
+  annotation: Pick<CommentAnnotationFields, "deleted">,
+): boolean {
+  return !isAnnotationDeleted(annotation);
+}
+
+export function countUnresolvedAnnotations(
+  annotations: readonly Pick<
+    CommentAnnotationFields,
+    "status" | "deleted" | "parentId"
+  >[],
+): number {
+  return annotations.filter(
+    (a) =>
+      isVisibleAnnotation(a) &&
+      isRootAnnotation(a) &&
+      !isAnnotationResolved(a),
+  ).length;
+}
+
+/** Skips deleted root annotations. Default order is newest first. */
+export function sortAnnotationsForDisplay<T extends CommentAnnotationFields>(
+  annotations: readonly T[],
+  order: "newest" | "oldest" = "newest",
+): T[] {
+  return [...annotations]
+    .filter(isVisibleAnnotation)
+    .filter(isRootAnnotation)
+    .sort((a, b) =>
+      order === "newest" ? b.timestamp - a.timestamp : a.timestamp - b.timestamp,
+    );
+}
+
+export function getAdjacentDisplayCommentId<T extends CommentAnnotationFields>(
+  sorted: readonly T[],
+  currentId: string,
+  direction: "prev" | "next",
+): string | null {
+  const index = sorted.findIndex((annotation) => annotation.id === currentId);
+  if (index === -1) return null;
+
+  const nextIndex = direction === "prev" ? index - 1 : index + 1;
+  if (nextIndex < 0 || nextIndex >= sorted.length) return null;
+  return sorted[nextIndex]?.id ?? null;
+}