proto-plugin 0.1.0

package/src/lib/prototypes/prototype-review-url.ts

@@ -0,0 +1,134 @@
+export type PrototypeReviewSidebarPanel =
+  | "comments"
+  | "variants"
+  | "change-log"
+  | "spec";
+
+export type PrototypeReviewTab = "tweaks" | "comments";
+
+export const REVIEW_PANEL_PARAM = "reviewPanel";
+export const REVIEW_VARIANT_SET_PARAM = "variantSet";
+export const REVIEW_TAB_PARAM = "reviewTab";
+export const REVIEW_TWEAKS_PARAM = "tweaks";
+export const REVIEW_SETTINGS_PARAM = "settings";
+export const REVIEW_PROD_REFERENCE_PARAM = "prodReference";
+
+export const REVIEW_URL_PARAM_KEYS = [
+  REVIEW_PANEL_PARAM,
+  REVIEW_VARIANT_SET_PARAM,
+  REVIEW_TAB_PARAM,
+  REVIEW_TWEAKS_PARAM,
+  REVIEW_SETTINGS_PARAM,
+  REVIEW_PROD_REFERENCE_PARAM,
+] as const;
+
+const VALID_REVIEW_PANELS = new Set<PrototypeReviewSidebarPanel>([
+  "comments",
+  "variants",
+  "change-log",
+  "spec",
+]);
+
+const VALID_REVIEW_TABS = new Set<PrototypeReviewTab>(["tweaks", "comments"]);
+
+export type PrototypeReviewUrlState = {
+  panel: PrototypeReviewSidebarPanel | null;
+  variantSetId: string | null;
+  activeTab: PrototypeReviewTab;
+  tweaksOpen: boolean;
+  settingsOpen: boolean;
+  prodReference: boolean;
+};
+
+export function hasReviewUrlParams(searchParams: URLSearchParams): boolean {
+  return REVIEW_URL_PARAM_KEYS.some((key) => searchParams.has(key));
+}
+
+export function parseReviewStateFromSearchParams(
+  searchParams: URLSearchParams,
+): PrototypeReviewUrlState {
+  const panelRaw = searchParams.get(REVIEW_PANEL_PARAM);
+  const panel =
+    panelRaw && VALID_REVIEW_PANELS.has(panelRaw as PrototypeReviewSidebarPanel)
+      ? (panelRaw as PrototypeReviewSidebarPanel)
+      : null;
+
+  const variantSetRaw = searchParams.get(REVIEW_VARIANT_SET_PARAM)?.trim();
+  const variantSetId = variantSetRaw ? variantSetRaw : null;
+
+  const tabRaw = searchParams.get(REVIEW_TAB_PARAM);
+  const activeTab =
+    tabRaw && VALID_REVIEW_TABS.has(tabRaw as PrototypeReviewTab)
+      ? (tabRaw as PrototypeReviewTab)
+      : "tweaks";
+
+  return {
+    panel,
+    variantSetId,
+    activeTab,
+    tweaksOpen: searchParams.get(REVIEW_TWEAKS_PARAM) === "1",
+    settingsOpen: searchParams.get(REVIEW_SETTINGS_PARAM) === "1",
+    prodReference: searchParams.get(REVIEW_PROD_REFERENCE_PARAM) === "1",
+  };
+}
+
+export function writeReviewStateToSearchParams(
+  searchParams: URLSearchParams,
+  state: {
+    open: boolean;
+    sidebarPanel: PrototypeReviewSidebarPanel | null;
+    activeVariantSetId: string | null;
+    activeTab: PrototypeReviewTab;
+    tweaksOpen: boolean;
+    settingsOpen: boolean;
+    prodReferenceAvailable: boolean;
+    showProdReference: boolean;
+  },
+): void {
+  for (const key of REVIEW_URL_PARAM_KEYS) {
+    searchParams.delete(key);
+  }
+
+  if (state.tweaksOpen) {
+    searchParams.set(REVIEW_TWEAKS_PARAM, "1");
+  }
+
+  if (state.settingsOpen) {
+    searchParams.set(REVIEW_SETTINGS_PARAM, "1");
+  }
+
+  if (state.prodReferenceAvailable && state.showProdReference) {
+    searchParams.set(REVIEW_PROD_REFERENCE_PARAM, "1");
+  }
+
+  if (!state.open || !state.sidebarPanel) {
+    return;
+  }
+
+  searchParams.set(REVIEW_PANEL_PARAM, state.sidebarPanel);
+
+  if (state.sidebarPanel === "variants" && state.activeVariantSetId) {
+    searchParams.set(REVIEW_VARIANT_SET_PARAM, state.activeVariantSetId);
+  }
+
+  if (state.sidebarPanel === "comments" && state.activeTab === "comments") {
+    searchParams.set(REVIEW_TAB_PARAM, "comments");
+  }
+}
+
+export function syncReviewStateToUrl(state: {
+  open: boolean;
+  sidebarPanel: PrototypeReviewSidebarPanel | null;
+  activeVariantSetId: string | null;
+  activeTab: PrototypeReviewTab;
+  tweaksOpen: boolean;
+  settingsOpen: boolean;
+  prodReferenceAvailable: boolean;
+  showProdReference: boolean;
+}): void {
+  if (typeof window === "undefined") return;
+
+  const url = new URL(window.location.href);
+  writeReviewStateToSearchParams(url.searchParams, state);
+  window.history.replaceState(null, "", url);
+}

package/src/lib/prototypes/prototype-share-link.ts

@@ -0,0 +1,175 @@
+import { resolveAnnotationTargetById } from "@prototype/lib/prototype-comments/core/annotation-target";
+
+export const SHARE_TARGET_PARAM = "shareTarget";
+export const SHARE_STATE_PARAM = "shareState";
+export const SHARE_COMMENT_PARAM = "shareComment";
+
+function toBase64Url(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function fromBase64Url(value: string): string {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padLength = (4 - (padded.length % 4)) % 4;
+  const binary = atob(padded + "=".repeat(padLength));
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+export function encodeShareState(state: unknown): string {
+  return toBase64Url(JSON.stringify(state));
+}
+
+export function decodeShareState<T = unknown>(encoded: string): T {
+  return JSON.parse(fromBase64Url(encoded)) as T;
+}
+
+export type ShareLinkParams = {
+  targetId: string;
+  state: unknown | null;
+};
+
+export function readShareLinkParams(
+  searchParams: URLSearchParams,
+): ShareLinkParams | null {
+  const targetId = searchParams.get(SHARE_TARGET_PARAM);
+  if (!targetId) return null;
+
+  const stateParam = searchParams.get(SHARE_STATE_PARAM);
+  if (!stateParam) {
+    return { targetId, state: null };
+  }
+
+  try {
+    return { targetId, state: decodeShareState(stateParam) };
+  } catch {
+    return { targetId, state: null };
+  }
+}
+
+export function readShareCommentParam(
+  searchParams: URLSearchParams,
+): string | null {
+  const commentId = searchParams.get(SHARE_COMMENT_PARAM);
+  return commentId?.trim() ? commentId : null;
+}
+
+export function pendingCommentRestoreKey(slug: string): string {
+  return `prototype-share-comment:${slug}`;
+}
+
+export function stashPendingCommentRestore(slug: string, commentId: string): void {
+  if (typeof window === "undefined") return;
+
+  try {
+    sessionStorage.setItem(pendingCommentRestoreKey(slug), commentId);
+  } catch {
+    // Ignore sessionStorage write failures in prototype preview.
+  }
+}
+
+export function readPendingCommentRestore(slug: string): string | null {
+  if (typeof window === "undefined") return null;
+
+  try {
+    const value = sessionStorage.getItem(pendingCommentRestoreKey(slug));
+    return value?.trim() ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearPendingCommentRestore(slug: string): void {
+  if (typeof window === "undefined") return;
+
+  try {
+    sessionStorage.removeItem(pendingCommentRestoreKey(slug));
+  } catch {
+    // Ignore sessionStorage write failures in prototype preview.
+  }
+}
+
+export function hasPendingCommentRestore(slug: string): boolean {
+  return readPendingCommentRestore(slug) != null;
+}
+
+/** URL param first; falls back to session stash so restore survives URL rewrites. */
+export function resolveShareCommentId(
+  searchParams: URLSearchParams,
+  slug: string | null,
+): string | null {
+  const fromUrl = readShareCommentParam(searchParams);
+  if (fromUrl) {
+    if (slug) stashPendingCommentRestore(slug, fromUrl);
+    return fromUrl;
+  }
+
+  return slug ? readPendingCommentRestore(slug) : null;
+}
+
+export function buildComponentShareLink(
+  targetId: string,
+  liveState: unknown,
+  options?: { commentId?: string | null },
+): string {
+  const url = new URL(window.location.href);
+  url.searchParams.set(SHARE_TARGET_PARAM, targetId);
+  url.searchParams.set(SHARE_STATE_PARAM, encodeShareState(liveState));
+  if (options?.commentId) {
+    url.searchParams.set(SHARE_COMMENT_PARAM, options.commentId);
+  }
+  return url.toString();
+}
+
+export function buildCommentShareLink(commentId: string): string {
+  const url = new URL(window.location.href);
+  url.searchParams.set(SHARE_COMMENT_PARAM, commentId);
+  return url.toString();
+}
+
+export function syncShareCommentParam(commentId: string | null): void {
+  const url = new URL(window.location.href);
+  if (commentId) {
+    if (url.searchParams.get(SHARE_COMMENT_PARAM) === commentId) return;
+    url.searchParams.set(SHARE_COMMENT_PARAM, commentId);
+  } else if (!url.searchParams.has(SHARE_COMMENT_PARAM)) {
+    return;
+  } else {
+    url.searchParams.delete(SHARE_COMMENT_PARAM);
+  }
+  window.history.replaceState(null, "", url);
+}
+
+export function clearShareCommentParam(url: URL): void {
+  url.searchParams.delete(SHARE_COMMENT_PARAM);
+}
+
+/** Removes component share params only; keeps `shareComment` for comment deep-link restore. */
+export function clearShareComponentParams(url: URL): void {
+  url.searchParams.delete(SHARE_TARGET_PARAM);
+  url.searchParams.delete(SHARE_STATE_PARAM);
+}
+
+export function clearShareLinkParams(url: URL): void {
+  clearShareComponentParams(url);
+  clearShareCommentParam(url);
+}
+
+export function scrollPrototypeTargetIntoView(targetId: string): void {
+  const element = resolveAnnotationTargetById(targetId);
+  if (!element) return;
+
+  window.requestAnimationFrame(() => {
+    window.requestAnimationFrame(() => {
+      element.scrollIntoView({ behavior: "smooth", block: "center" });
+    });
+  });
+}

package/src/lib/prototypes/prototype-state-canvas-constants.ts

@@ -0,0 +1,118 @@
+/** Layout width of a state-map node card (CSS px). */
+export const PROTOTYPE_STATE_NODE_WIDTH = 220;
+
+/** Preview image area height inside a state-map node (CSS px). */
+export const PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT = 132;
+
+/** Label row height below the wireframe preview (CSS px). */
+export const PROTOTYPE_STATE_NODE_LABEL_HEIGHT = 36;
+
+/** Single nested-state (callout) row height (CSS px). */
+export const PROTOTYPE_STATE_NODE_CALLOUT_HEIGHT = 28;
+
+/** Nested-state row height when a hint label is shown (CSS px). */
+export const PROTOTYPE_STATE_NODE_CALLOUT_WITH_HINT_HEIGHT = 36;
+
+/** Gap between nested-state rows (CSS px). */
+export const PROTOTYPE_STATE_NODE_CALLOUT_GAP = 4;
+
+/** Padding around the nested-state tray (CSS px). */
+export const PROTOTYPE_STATE_NODE_CALLOUT_PADDING = 8;
+
+/** Horizontal gap between state-map node columns (CSS px). */
+export const PROTOTYPE_STATE_NODE_COLUMN_GAP = 56;
+
+/** Vertical gap between a section label and the nodes below it (CSS px). */
+export const PROTOTYPE_STATE_SECTION_TO_NODES = 40;
+
+/** Vertical gap between rows of nodes (CSS px). */
+export const PROTOTYPE_STATE_NODE_ROW_GAP = 48;
+
+/** Padding from the canvas origin (CSS px). */
+export const PROTOTYPE_STATE_CANVAS_PADDING = 48;
+
+export type StateCanvasCalloutDimensions = {
+  hint?: string;
+};
+
+export function getStateCanvasCalloutHeight(
+  callout: StateCanvasCalloutDimensions,
+): number {
+  return callout.hint
+    ? PROTOTYPE_STATE_NODE_CALLOUT_WITH_HINT_HEIGHT
+    : PROTOTYPE_STATE_NODE_CALLOUT_HEIGHT;
+}
+
+/** Preview + label area height (excludes nested-state callouts). */
+export function getStateCanvasNodeBodyHeight(): number {
+  return PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT + PROTOTYPE_STATE_NODE_LABEL_HEIGHT;
+}
+
+/** Canvas Y of the title row for a state or nested-state annotation target. */
+export function getStateMapAnnotationTitleTop(
+  nodeY: number,
+  targetId: string,
+  nodeId: string,
+  callouts?: readonly (StateCanvasCalloutDimensions & { id: string })[],
+): number {
+  if (targetId === nodeId) {
+    return nodeY + PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT;
+  }
+
+  if (!callouts?.length) {
+    return nodeY + PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT;
+  }
+
+  let offset =
+    getStateCanvasNodeBodyHeight() + PROTOTYPE_STATE_NODE_CALLOUT_PADDING;
+
+  for (const callout of callouts) {
+    if (callout.id === targetId) {
+      return nodeY + offset;
+    }
+    offset +=
+      getStateCanvasCalloutHeight(callout) + PROTOTYPE_STATE_NODE_CALLOUT_GAP;
+  }
+
+  return nodeY + PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT;
+}
+
+/** Total rendered height of a state-map node, including nested states. */
+export function getStateCanvasNodeHeight(
+  callouts?: readonly StateCanvasCalloutDimensions[],
+): number {
+  const bodyHeight = getStateCanvasNodeBodyHeight();
+  const count = callouts?.length ?? 0;
+  if (count === 0) return bodyHeight;
+
+  const calloutsHeight = callouts.reduce((sum, callout, index) => {
+    const gap = index > 0 ? PROTOTYPE_STATE_NODE_CALLOUT_GAP : 0;
+    return sum + gap + getStateCanvasCalloutHeight(callout);
+  }, 0);
+
+  return bodyHeight + PROTOTYPE_STATE_NODE_CALLOUT_PADDING * 2 + calloutsHeight;
+}
+
+/** X coordinate for a zero-based column index. */
+export function stateCanvasColumnX(columnIndex: number): number {
+  return (
+    PROTOTYPE_STATE_CANVAS_PADDING +
+    columnIndex * (PROTOTYPE_STATE_NODE_WIDTH + PROTOTYPE_STATE_NODE_COLUMN_GAP)
+  );
+}
+
+/** Maximum canvas zoom — thumbnails are generated for this scale. */
+export const PROTOTYPE_STATE_CANVAS_MAX_SCALE = 4.5;
+
+/** Device pixel ratio used when rasterizing state thumbnails. */
+export const PROTOTYPE_STATE_SCREENSHOT_THUMB_PIXEL_RATIO = 2;
+
+export function getStateScreenshotThumbSize(): { width: number; height: number } {
+  const scale =
+    PROTOTYPE_STATE_CANVAS_MAX_SCALE * PROTOTYPE_STATE_SCREENSHOT_THUMB_PIXEL_RATIO;
+
+  return {
+    width: Math.round(PROTOTYPE_STATE_NODE_WIDTH * scale),
+    height: Math.round(PROTOTYPE_STATE_NODE_PREVIEW_HEIGHT * scale),
+  };
+}

package/src/lib/prototypes/prototype-state-canvas-types.ts

@@ -0,0 +1,159 @@
+import type { ReactNode } from "react";
+
+export type PrototypeStateCanvasNodeCallout<T extends string = string> = {
+  id: T;
+  label: string;
+  hint?: string;
+  /** Planning note — what this variant should do or communicate. */
+  annotation?: string;
+  /** Maps bullet index (or @suffix id) to wireframe highlight region keys. */
+  highlightRegions?: readonly string[];
+};
+
+export type PrototypeStateCanvasNode<T extends string = string> = {
+  id: T;
+  label: string;
+  /** Canvas coordinates in px from the flowchart origin. */
+  x: number;
+  y: number;
+  /** Nested options rendered below the node — not separate canvas nodes. */
+  callouts?: PrototypeStateCanvasNodeCallout<T>[];
+  /** Planning note — what this screen should do, triggers, open questions. */
+  annotation?: string;
+  /** Maps bullet index (or @suffix id) to wireframe highlight region keys. */
+  highlightRegions?: readonly string[];
+};
+
+export type PrototypeStateCanvasEdge<T extends string = string> = {
+  from: T;
+  to: T;
+  /** Dashed lines for alternate / empty-state branches. */
+  dashed?: boolean;
+};
+
+export type PrototypeStateCanvasSection = {
+  label: string;
+  /** Top offset of the section label in canvas px. */
+  y: number;
+  /** Group-level planning note for this region of the map. */
+  annotation?: string;
+};
+
+export const PROTOTYPE_STATE_MAP_RETURN_TO_PARAM = "returnTo";
+
+export function getDefaultPrototypeStateMapPath(slug: string): string {
+  return `/prototypes/${slug}/states`;
+}
+
+/** Relative path (including query) to restore when leaving the map without picking a state. */
+export function parseStateMapReturnTo(
+  searchParams: URLSearchParams,
+): string | null {
+  const returnTo = searchParams.get(PROTOTYPE_STATE_MAP_RETURN_TO_PARAM);
+  if (!returnTo?.startsWith("/") || returnTo.startsWith("//")) {
+    return null;
+  }
+  return returnTo;
+}
+
+export function buildStateMapHref(
+  pagePath: string,
+  returnTo: string,
+  searchParams?: URLSearchParams,
+): string {
+  const params = new URLSearchParams(searchParams?.toString() ?? "");
+  params.set(PROTOTYPE_STATE_MAP_RETURN_TO_PARAM, returnTo);
+  const query = params.toString();
+  return query ? `${pagePath}?${query}` : pagePath;
+}
+
+export type StateMapHighlightRect = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+};
+
+export type PrototypeStateCanvasConfig<T extends string = string> = {
+  /** When omitted, no node appears selected — the map is a stateless picker. */
+  activeStateId?: T;
+  onStateSelect: (id: T) => void;
+  nodes: PrototypeStateCanvasNode<T>[];
+  edges: PrototypeStateCanvasEdge<T>[];
+  sections?: PrototypeStateCanvasSection[];
+  renderWireframe: (nodeId: T) => ReactNode;
+  /** Percent-based overlay regions for screenshot previews (0–100). */
+  getHighlightRegions?: (
+    nodeId: T,
+  ) => Partial<Record<string, StateMapHighlightRect>> | undefined;
+  /** Route for the full-page state map (toolbar link target). */
+  pagePath?: string;
+  /** Total scrollable canvas size. Defaults derived from node bounds. */
+  canvasWidth?: number;
+  canvasHeight?: number;
+};
+
+export type PrototypeStateMapAnnotationEntry = {
+  id: string;
+  label: string;
+  annotation: string;
+  kind: "section" | "state" | "variant";
+  parentLabel?: string;
+};
+
+export function stateMapHasAnnotations<T extends string>(
+  config: Pick<PrototypeStateCanvasConfig<T>, "nodes" | "sections">,
+): boolean {
+  if (config.sections?.some((section) => section.annotation?.trim())) {
+    return true;
+  }
+
+  return config.nodes.some((node) => {
+    if (node.annotation?.trim()) return true;
+    return node.callouts?.some((callout) => callout.annotation?.trim()) ?? false;
+  });
+}
+
+export function buildStateMapAnnotationEntries<T extends string>(
+  nodes: readonly PrototypeStateCanvasNode<T>[],
+  sections?: readonly PrototypeStateCanvasSection[],
+): PrototypeStateMapAnnotationEntry[] {
+  const entries: PrototypeStateMapAnnotationEntry[] = [];
+
+  for (const section of sections ?? []) {
+    const annotation = section.annotation?.trim();
+    if (!annotation) continue;
+    entries.push({
+      id: `section:${section.label}`,
+      label: section.label,
+      annotation,
+      kind: "section",
+    });
+  }
+
+  for (const node of nodes) {
+    const nodeAnnotation = node.annotation?.trim();
+    if (nodeAnnotation) {
+      entries.push({
+        id: node.id,
+        label: node.label,
+        annotation: nodeAnnotation,
+        kind: "state",
+      });
+    }
+
+    for (const callout of node.callouts ?? []) {
+      const calloutAnnotation = callout.annotation?.trim();
+      if (!calloutAnnotation) continue;
+      entries.push({
+        id: callout.id,
+        label: callout.label,
+        annotation: calloutAnnotation,
+        kind: "variant",
+        parentLabel: node.label,
+      });
+    }
+  }
+
+  return entries;
+}

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

@@ -0,0 +1,39 @@
+export const PROTOTYPE_STATE_SCREENSHOT_CAPTURED_EVENT =
+  "prototype-state-screenshot-captured";
+
+export type PrototypeStateScreenshotCapturedDetail = {
+  slug: string;
+  stateId: string;
+  version: number;
+};
+
+export function sanitizeStateIdForFilename(stateId: string): string {
+  return stateId.replace(/:/g, "--");
+}
+
+export function stateScreenshotManifestKey(slug: string, stateId: string): string {
+  return `${slug}/states/${sanitizeStateIdForFilename(stateId)}`;
+}
+
+export function stateScreenshotPublicPath(slug: string, stateId: string): string {
+  return `/prototypes/screenshots/${slug}/states/${sanitizeStateIdForFilename(stateId)}.png`;
+}
+
+export function stateScreenshotSrc(
+  slug: string,
+  stateId: string,
+  version: number | undefined,
+): string {
+  const basePath = stateScreenshotPublicPath(slug, stateId);
+  if (!version) return basePath;
+  return `${basePath}?v=${version}`;
+}
+
+export function dispatchPrototypeStateScreenshotCaptured(
+  detail: PrototypeStateScreenshotCapturedDetail,
+): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(
+    new CustomEvent(PROTOTYPE_STATE_SCREENSHOT_CAPTURED_EVENT, { detail }),
+  );
+}