@buoy-gg/events 2.1.1 → 2.1.3

package/lib/commonjs/utils/eventExportFormatter.js

@@ -8,6 +8,7 @@ exports.filterEvents = filterEvents;
 exports.generateExport = generateExport;
 exports.generateJsonExport = generateJsonExport;
 exports.generateMarkdownExport = generateMarkdownExport;
+exports.generateMermaidExport = generateMermaidExport;
 exports.generatePlaintextExport = generatePlaintextExport;
 exports.getExportSummary = getExportSummary;
 /**
@@ -55,7 +56,8 @@ const SOURCE_LABELS = {
   "react-query": "Query",
   "react-query-query": "Query",
   "react-query-mutation": "Mutation",
-  route: "Route"
+  route: "Route",
+  render: "Render"
 };
 
 // ============================================================================
@@ -1077,6 +1079,779 @@ function generatePlaintextExport(events, settings) {
   return lines.join("\n");
 }
 
+// ============================================================================
+// MERMAID SEQUENCE DIAGRAM EXPORT
+// ============================================================================
+
+/**
+ * Participant configuration for Mermaid sequence diagrams
+ */
+
+/**
+ * Participant definitions - map event sources to diagram actors
+ * Organized by client vs server for grouping
+ * Note: Storage types are split for clarity
+ */
+const MERMAID_PARTICIPANTS = [
+// Client-side
+{
+  id: "U",
+  icon: "👤",
+  label: "User",
+  sources: [],
+  group: "client"
+}, {
+  id: "App",
+  icon: "📱",
+  label: "App",
+  sources: ["route", "render"],
+  group: "client"
+}, {
+  id: "Async",
+  icon: "💾",
+  label: "AsyncStorage",
+  sources: ["storage-async"],
+  group: "client"
+}, {
+  id: "MMKV",
+  icon: "⚡",
+  label: "MMKV",
+  sources: ["storage-mmkv"],
+  group: "client"
+}, {
+  id: "Redux",
+  icon: "🔄",
+  label: "Redux",
+  sources: ["redux"],
+  group: "client"
+},
+// Server-side / External
+{
+  id: "API",
+  icon: "🌐",
+  label: "API",
+  sources: ["network"],
+  group: "server"
+}, {
+  id: "Cache",
+  icon: "📦",
+  label: "QueryCache",
+  sources: ["react-query", "react-query-query", "react-query-mutation"],
+  group: "server"
+}];
+
+/**
+ * Get the Mermaid participant ID for an event source
+ */
+function getParticipantId(source) {
+  const participant = MERMAID_PARTICIPANTS.find(p => p.sources.includes(source));
+  return participant?.id || "App";
+}
+
+/**
+ * Detect which participants are needed based on events
+ */
+function detectParticipants(events) {
+  const sourcesInUse = new Set();
+  for (const event of events) {
+    sourcesInUse.add(event.source);
+  }
+  const participants = [];
+
+  // Always include User and App
+  participants.push(MERMAID_PARTICIPANTS[0]); // User
+  participants.push(MERMAID_PARTICIPANTS[1]); // App
+
+  // Add other participants based on event sources present
+  for (const participant of MERMAID_PARTICIPANTS.slice(2)) {
+    if (participant.sources.some(s => sourcesInUse.has(s))) {
+      participants.push(participant);
+    }
+  }
+  return participants;
+}
+
+/**
+ * Check if we should use participant grouping (boxes)
+ */
+function shouldUseGroups(participants) {
+  const hasClient = participants.some(p => p.group === "client");
+  const hasServer = participants.some(p => p.group === "server");
+  return hasClient && hasServer && participants.length >= 3;
+}
+
+/**
+ * Format duration for Mermaid notes
+ */
+function formatMermaidDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+/**
+ * Escape text for Mermaid (handle special characters)
+ */
+function escapeMermaidText(text) {
+  return text.replace(/[#;:]/g, " ") // Remove characters with special meaning
+  .replace(/[\n\r]/g, " ") // Replace newlines with spaces
+  .replace(/"/g, "'") // Replace double quotes with single
+  .replace(/\s+/g, " ") // Collapse multiple spaces
+  .trim();
+}
+
+/**
+ * Check if a storage key is internal/devtools tracking
+ * Be conservative - only filter obvious internal keys
+ */
+function isInternalStorageKey(key) {
+  const internalPatterns = ["last-route", "@dev/last", "__debug", "_persist", "devtools/internal"];
+  const lowerKey = key.toLowerCase();
+  return internalPatterns.some(p => lowerKey.includes(p));
+}
+
+/**
+ * Format bytes to human readable size
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * Estimate size of data in bytes
+ */
+function estimateDataSize(data) {
+  try {
+    return JSON.stringify(data).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Get canonical URL for duplicate detection (strip timestamps, debug params)
+ */
+function getCanonicalUrl(url) {
+  try {
+    const urlObj = new URL(url, "http://localhost");
+    // Remove common cache-busting/debug params
+    const paramsToRemove = ["timestamp", "t", "_t", "debug", "client", "version", "cache", "_"];
+    paramsToRemove.forEach(p => urlObj.searchParams.delete(p));
+    return urlObj.pathname + (urlObj.searchParams.toString() ? "?" + urlObj.searchParams.toString() : "");
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Get a readable short name from a storage key
+ */
+function getStorageKeyName(key) {
+  // Remove common prefixes
+  let name = key.replace(/^@[\w-]+\//, "") // Remove @prefix/
+  .replace(/^devtools\//, "").replace(/^dev\//, "").replace(/^buoy\//, "").replace(/^pokemon\//, ""); // Remove pokemon/ prefix for this app
+
+  // Get last meaningful segment
+  const segments = name.split("/").filter(Boolean);
+  if (segments.length > 1) {
+    name = segments.slice(-1).join("/"); // Just the last segment
+  }
+
+  // Humanize common patterns
+  name = name.replace(/-/g, " ").replace(/_/g, " ");
+
+  // Title case
+  name = name.split(" ").map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(" ");
+
+  // Common renames for clarity
+  if (name.toLowerCase() === "saved") name = "Favorites";
+  return name.substring(0, 20);
+}
+
+/**
+ * Extract entity name from URL path (e.g., /pokemon/charizard -> Charizard)
+ */
+function extractEntityFromPath(url) {
+  // Strip query params first
+  let path = url;
+  try {
+    const urlObj = new URL(url, "http://localhost");
+    path = urlObj.pathname;
+  } catch {
+    // If URL parsing fails, try to strip query params manually
+    const queryIndex = path.indexOf("?");
+    if (queryIndex > 0) {
+      path = path.substring(0, queryIndex);
+    }
+  }
+
+  // Common patterns: /resource/:id, /resource/:name
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length >= 2) {
+    const lastSegment = segments[segments.length - 1];
+    // If it looks like an ID (number or uuid), use the resource name
+    if (/^\d+$/.test(lastSegment) || /^[a-f0-9-]{36}$/i.test(lastSegment)) {
+      return null;
+    }
+    // Humanize the last segment (e.g., charizard -> Charizard)
+    return lastSegment.charAt(0).toUpperCase() + lastSegment.slice(1);
+  }
+  if (segments.length === 1) {
+    return segments[0].charAt(0).toUpperCase() + segments[0].slice(1);
+  }
+  return null;
+}
+
+/**
+ * Get human-readable action from HTTP method + path
+ */
+function getHumanReadableApiAction(method, url) {
+  try {
+    const urlObj = new URL(url, "http://localhost");
+    let path = urlObj.pathname;
+
+    // Handle GraphQL specially
+    if (path.includes("graphql")) {
+      return "GraphQL Request";
+    }
+
+    // Remove API prefixes
+    path = path.replace(/^\/api\/v\d+/, "").replace(/^\/api/, "");
+    const entity = extractEntityFromPath(path);
+    const segments = path.split("/").filter(Boolean);
+    const resource = segments[0] ? segments[0].charAt(0).toUpperCase() + segments[0].slice(1) : "Data";
+
+    // Check for search/query patterns
+    const hasSearchQuery = urlObj.searchParams.has("q") || urlObj.searchParams.has("query") || urlObj.searchParams.has("search");
+
+    // Generate human-readable action based on method
+    switch (method.toUpperCase()) {
+      case "GET":
+        if (hasSearchQuery) {
+          const query = urlObj.searchParams.get("q") || urlObj.searchParams.get("query") || urlObj.searchParams.get("search");
+          if (query) return `Search "${query}"`;
+          return `Search ${resource}`;
+        }
+        if (entity) return `Fetch ${entity}`;
+        return `Fetch ${resource}`;
+      case "POST":
+        if (path.includes("search")) return `Search ${resource}`;
+        if (entity) return `Create ${entity}`;
+        return `Create ${resource}`;
+      case "PUT":
+      case "PATCH":
+        if (entity) return `Update ${entity}`;
+        return `Update ${resource}`;
+      case "DELETE":
+        if (entity) return `Delete ${entity}`;
+        return `Delete ${resource}`;
+      default:
+        return `${method} ${resource}`;
+    }
+  } catch {
+    return `${method} request`;
+  }
+}
+
+/**
+ * Get human-readable route label
+ */
+function getHumanReadableRoute(pathname) {
+  if (pathname === "/" || pathname === "") return "Home";
+  const segments = pathname.split("/").filter(Boolean);
+  if (segments.length === 0) return "Home";
+
+  // Handle common patterns
+  if (segments.length === 1) {
+    // /pokemon -> Pokemon List
+    const name = segments[0].charAt(0).toUpperCase() + segments[0].slice(1);
+    return `${name} List`;
+  }
+  if (segments.length >= 2) {
+    // /pokemon/charizard -> Charizard Details
+    const entity = segments[segments.length - 1];
+    // Check if it's a numeric ID
+    if (/^\d+$/.test(entity)) {
+      const resource = segments[0].charAt(0).toUpperCase() + segments[0].slice(1);
+      return `${resource} #${entity}`;
+    }
+    const entityName = entity.charAt(0).toUpperCase() + entity.slice(1);
+    return `${entityName} Details`;
+  }
+  return pathname;
+}
+
+/**
+ * Format a single event as Mermaid sequence messages
+ * Returns both the messages and any notes to add
+ * Returns null if the event should be skipped (internal/devtools)
+ */
+function formatMermaidEvent(event, _settings, baseTimestamp) {
+  const messages = [];
+  const notes = [];
+  const relativeTime = formatMermaidDuration(event.timestamp - baseTimestamp);
+  switch (event.source) {
+    case "route":
+      {
+        const data = event.originalEvent;
+        const pathname = String(data?.pathname || event.title);
+        const previousPathname = data?.previousPathname;
+        const timeSincePrevious = data?.timeSincePrevious;
+        const routeLabel = getHumanReadableRoute(pathname);
+        const fromLabel = previousPathname ? getHumanReadableRoute(previousPathname) : null;
+
+        // Show navigation with clear from → to pattern
+        if (fromLabel) {
+          messages.push(`U->>App: ${fromLabel} → ${routeLabel}`);
+          // Show how long user spent on previous screen
+          if (timeSincePrevious && timeSincePrevious > 0) {
+            notes.push(`Note right of App: ${formatMermaidDuration(timeSincePrevious)} on ${fromLabel}`);
+          }
+        } else {
+          messages.push(`U->>App: Open ${routeLabel}`);
+        }
+        break;
+      }
+    case "network":
+      {
+        const data = event.originalEvent;
+        const method = data?.method || "GET";
+        const url = data?.url || "";
+        const status = data?.status;
+        const duration = data?.duration;
+        const responseData = data?.response || data?.data || data?.body;
+        // Try to get size from various possible fields
+        const responseSize = data?.responseSize || data?.size || data?.contentLength;
+
+        // Get human-readable action
+        const action = getHumanReadableApiAction(method, url);
+        const entity = extractEntityFromPath(url);
+
+        // Request with activation
+        messages.push(`App->>+API: ${action}`);
+
+        // Response with entity context if available
+        if (event.status === "error") {
+          const statusText = status ? `${status} Error` : "Failed";
+          messages.push(`API--x-App: ${statusText}`);
+        } else {
+          let response = entity ? `✓ ${entity}` : "✓ Success";
+          messages.push(`API-->>-App: ${response}`);
+        }
+
+        // Build note with duration and size
+        const noteParts = [];
+        if (duration) {
+          noteParts.push(formatMermaidDuration(duration));
+        }
+        // Add response size - try explicit size first, then estimate
+        if (responseSize && responseSize > 0) {
+          noteParts.push(formatBytes(responseSize));
+        } else if (responseData) {
+          const size = estimateDataSize(responseData);
+          if (size > 1024) {
+            // Only show if > 1KB
+            noteParts.push(formatBytes(size));
+          }
+        }
+        if (noteParts.length > 0) {
+          notes.push(`Note right of API: ${noteParts.join(" · ")}`);
+        }
+        break;
+      }
+    case "storage-async":
+    case "storage-mmkv":
+      {
+        const data = event.originalEvent;
+        const innerData = data?.data;
+        const action = data?.action || "access";
+        const key = innerData?.key || "data";
+
+        // Skip internal devtools storage
+        if (isInternalStorageKey(key)) {
+          return {
+            messages: [],
+            notes: [],
+            skip: true
+          };
+        }
+        const keyName = getStorageKeyName(key);
+        const storeId = event.source === "storage-mmkv" ? "MMKV" : "Async";
+
+        // Helper to get item identifier (handles both objects and strings)
+        const getItemId = item => {
+          if (typeof item === "string") return item;
+          if (typeof item === "number") return String(item);
+          if (typeof item === "object" && item) {
+            if ("name" in item) return String(item.name);
+            if ("id" in item) return String(item.id);
+          }
+          return null;
+        };
+
+        // Helper to capitalize first letter
+        const capitalize = s => s.charAt(0).toUpperCase() + s.slice(1);
+
+        // Analyze the change to determine action and entity
+        let actionIcon = "";
+        let actionVerb = "";
+        let entityName = "";
+        let countInfo = "";
+        const prevValue = innerData?.prevValue;
+        const newValue = innerData?.value;
+
+        // Handle array comparisons (most common for collections)
+        if (Array.isArray(prevValue) && Array.isArray(newValue)) {
+          const prevLen = prevValue.length;
+          const newLen = newValue.length;
+          countInfo = `${prevLen} → ${newLen} items`;
+          if (newLen > prevLen) {
+            // Items were added
+            actionIcon = "➕";
+            actionVerb = "Add";
+            // Find what was added
+            const prevSet = new Set(prevValue.map(getItemId).filter(Boolean));
+            for (const item of newValue) {
+              const id = getItemId(item);
+              if (id && !prevSet.has(id)) {
+                entityName = capitalize(id);
+                break;
+              }
+            }
+          } else if (newLen < prevLen) {
+            // Items were removed
+            actionIcon = "➖";
+            actionVerb = "Remove";
+            // Find what was removed
+            const newSet = new Set(newValue.map(getItemId).filter(Boolean));
+            for (const item of prevValue) {
+              const id = getItemId(item);
+              if (id && !newSet.has(id)) {
+                entityName = capitalize(id);
+                break;
+              }
+            }
+          } else {
+            // Same length - update
+            actionIcon = "📝";
+            actionVerb = "Update";
+          }
+        } else if (Array.isArray(newValue) && (!prevValue || Array.isArray(prevValue) && prevValue.length === 0)) {
+          // Adding first item(s) - prevValue is null/undefined or empty array
+          actionIcon = "➕";
+          actionVerb = "Add";
+          countInfo = `→ ${newValue.length} items`;
+          if (newValue.length > 0) {
+            const id = getItemId(newValue[0]);
+            if (id) entityName = capitalize(id);
+          }
+        } else if (Array.isArray(prevValue) && (!newValue || Array.isArray(newValue) && newValue.length === 0)) {
+          // Removing all items
+          actionIcon = "➖";
+          actionVerb = "Clear";
+          countInfo = `${prevValue.length} → 0 items`;
+        } else if (action === "getItem") {
+          actionIcon = "📖";
+          actionVerb = "Load";
+        } else if (action === "removeItem") {
+          actionIcon = "➖";
+          actionVerb = "Remove";
+        } else if (action === "clear") {
+          actionIcon = "🗑️";
+          actionVerb = "Clear";
+        } else {
+          // Default for setItem without prev/new comparison
+          actionIcon = "💾";
+          actionVerb = "Save";
+        }
+
+        // Build the message
+        let message;
+        if (entityName) {
+          message = `App->>${storeId}: ${actionIcon} ${actionVerb} ${entityName} → ${keyName}`;
+        } else {
+          message = `App->>${storeId}: ${actionIcon} ${actionVerb} ${keyName}`;
+        }
+        messages.push(message);
+
+        // Add note with count info
+        if (countInfo) {
+          notes.push(`Note right of ${storeId}: ${countInfo}`);
+        }
+        break;
+      }
+    case "react-query":
+    case "react-query-query":
+      {
+        const data = event.originalEvent;
+        const type = data?.type || "";
+        const queryKey = data?.queryKey;
+        const duration = data?.duration;
+
+        // Format query key as human-readable
+        let keyLabel = "data";
+        if (Array.isArray(queryKey) && queryKey.length > 0) {
+          // Try to make it readable: ["pokemon", "charizard"] -> "Charizard"
+          const lastKey = queryKey[queryKey.length - 1];
+          if (typeof lastKey === "string" && !/^\d+$/.test(lastKey)) {
+            keyLabel = lastKey.charAt(0).toUpperCase() + lastKey.slice(1);
+          } else if (queryKey.length > 1 && typeof queryKey[0] === "string") {
+            keyLabel = queryKey[0].charAt(0).toUpperCase() + queryKey[0].slice(1);
+          }
+        }
+        if (type.includes("start") || type.includes("fetch") || event.status === "pending") {
+          messages.push(`App->>+Cache: Fetch ${keyLabel}`);
+        } else if (event.status === "error") {
+          messages.push(`Cache--x-App: Failed to load`);
+        } else if (event.status === "success") {
+          let response = `✓ ${keyLabel} ready`;
+          if (duration) {
+            response += ` (${formatMermaidDuration(duration)})`;
+          }
+          messages.push(`Cache-->>-App: ${response}`);
+        } else if (type.includes("invalidate")) {
+          messages.push(`App->>Cache: Refresh ${keyLabel}`);
+        } else {
+          messages.push(`Cache-->>App: ${escapeMermaidText(type)}`);
+        }
+        break;
+      }
+    case "react-query-mutation":
+      {
+        const data = event.originalEvent;
+        const type = data?.type || "";
+        const mutationKey = data?.mutationKey;
+        const duration = data?.duration;
+        let actionLabel = "Update";
+        if (Array.isArray(mutationKey) && mutationKey.length > 0) {
+          const key = String(mutationKey[0]);
+          // Common mutation patterns
+          if (key.includes("add") || key.includes("create")) actionLabel = "Add";else if (key.includes("delete") || key.includes("remove")) actionLabel = "Delete";else if (key.includes("update") || key.includes("edit")) actionLabel = "Update";else actionLabel = key.charAt(0).toUpperCase() + key.slice(1);
+        }
+        if (type.includes("start") || type.includes("loading") || event.status === "pending") {
+          messages.push(`App->>+Cache: ${actionLabel}`);
+        } else if (event.status === "error") {
+          messages.push(`Cache--x-App: ${actionLabel} failed`);
+        } else if (event.status === "success") {
+          let response = `✓ ${actionLabel} complete`;
+          if (duration) {
+            response += ` (${formatMermaidDuration(duration)})`;
+          }
+          messages.push(`Cache-->>-App: ${response}`);
+        }
+        break;
+      }
+    case "redux":
+      {
+        const data = event.originalEvent;
+        const actionType = data?.type || event.title;
+        const hasChange = data?.hasStateChange;
+        const diffSummary = data?.diffSummary;
+
+        // Parse action type into human-readable form
+        // e.g., "cart/addItem" -> "Add Item to Cart"
+        const parts = actionType.split("/");
+        let actionLabel;
+        if (parts.length >= 2) {
+          const slice = parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+          let action = parts[1].replace(/([A-Z])/g, " $1") // camelCase to spaces
+          .replace(/(pending|fulfilled|rejected)$/i, "").trim();
+          action = action.charAt(0).toUpperCase() + action.slice(1);
+          actionLabel = `${action} (${slice})`;
+        } else {
+          actionLabel = escapeMermaidText(actionType).substring(0, 25);
+        }
+        messages.push(`App->>Redux: ${actionLabel}`);
+        if (hasChange === false) {
+          notes.push(`Note right of Redux: No change`);
+        } else if (diffSummary) {
+          notes.push(`Note right of Redux: ${escapeMermaidText(diffSummary).substring(0, 35)}`);
+        }
+        break;
+      }
+    case "render":
+      {
+        const data = event.originalEvent;
+        const renderData = data?.renderData;
+        const componentName = escapeMermaidText(event.title).substring(0, 20);
+        const cause = renderData?.cause || "update";
+
+        // Make cause more human-readable
+        const causeLabel = cause === "mount" ? "mounted" : cause === "props" ? "props changed" : cause === "state" ? "state changed" : cause === "context" ? "context changed" : cause === "parent" ? "parent re-rendered" : cause === "hooks" ? "hook changed" : cause;
+        messages.push(`App->>App: Render ${componentName}`);
+        notes.push(`Note right of App: ${causeLabel}`);
+        break;
+      }
+    default:
+      {
+        messages.push(`App->>App: ${escapeMermaidText(event.title).substring(0, 30)}`);
+      }
+  }
+  return {
+    messages,
+    notes
+  };
+}
+
+/**
+ * Generate Mermaid sequence diagram export
+ */
+function generateMermaidExport(events, settings) {
+  const filtered = filterEvents(events, settings);
+  if (filtered.length === 0) {
+    return "sequenceDiagram\n    participant U as 👤 User\n    participant App as 📱 App\n    Note over U,App: No events captured";
+  }
+
+  // Sort by timestamp (oldest first for timeline)
+  const sorted = [...filtered].sort((a, b) => a.timestamp - b.timestamp);
+  const baseTimestamp = sorted[0].timestamp;
+
+  // Detect participants
+  const participants = detectParticipants(sorted);
+  const useGroups = shouldUseGroups(participants);
+  const lines = ["sequenceDiagram"];
+  lines.push("    autonumber");
+  lines.push("");
+
+  // Add participants with optional grouping
+  if (useGroups) {
+    const clientParticipants = participants.filter(p => p.group === "client");
+    const serverParticipants = participants.filter(p => p.group === "server");
+    if (clientParticipants.length > 0) {
+      lines.push("    box rgb(240, 248, 255) Client");
+      for (const p of clientParticipants) {
+        lines.push(`        participant ${p.id} as ${p.icon} ${p.label}`);
+      }
+      lines.push("    end");
+    }
+    if (serverParticipants.length > 0) {
+      lines.push("    box rgb(255, 248, 240) External");
+      for (const p of serverParticipants) {
+        lines.push(`        participant ${p.id} as ${p.icon} ${p.label}`);
+      }
+      lines.push("    end");
+    }
+  } else {
+    for (const p of participants) {
+      lines.push(`    participant ${p.id} as ${p.icon} ${p.label}`);
+    }
+  }
+  lines.push("");
+
+  // Calculate session summary stats
+  const sessionDuration = sorted[sorted.length - 1].timestamp - baseTimestamp;
+  const networkEvents = sorted.filter(e => e.source === "network");
+  const totalBytes = networkEvents.reduce((sum, e) => {
+    const data = e.originalEvent;
+    const size = data?.responseSize || data?.size || 0;
+    return sum + size;
+  }, 0);
+  const errorCount = sorted.filter(e => e.status === "error").length;
+
+  // Build summary parts
+  const summaryParts = [];
+  summaryParts.push(`⏱️ ${formatMermaidDuration(sessionDuration)}`);
+  summaryParts.push(`📊 ${sorted.length} events`);
+  if (networkEvents.length > 0) {
+    summaryParts.push(`🌐 ${networkEvents.length} API calls`);
+  }
+  if (totalBytes > 0) {
+    summaryParts.push(`📦 ${formatBytes(totalBytes)}`);
+  }
+  if (errorCount > 0) {
+    summaryParts.push(`❌ ${errorCount} errors`);
+  }
+
+  // Add session summary header
+  lines.push(`    Note over U,API: ${summaryParts.join(" · ")}`);
+  lines.push("");
+
+  // Track for duplicate detection - use canonical URLs (without cache-busting params)
+  const recentNetworkUrls = new Map();
+
+  // Process events
+  let skippedCount = 0;
+  for (const event of sorted) {
+    const result = formatMermaidEvent(event, settings, baseTimestamp);
+
+    // Skip internal/devtools events
+    if (result.skip) {
+      skippedCount++;
+      continue;
+    }
+    const {
+      messages,
+      notes
+    } = result;
+
+    // Check for duplicate network requests using canonical URL
+    let isDuplicate = false;
+    let duplicateInfo = "";
+    if (event.source === "network") {
+      const data = event.originalEvent;
+      const url = data?.url;
+      if (url) {
+        const canonicalUrl = getCanonicalUrl(url);
+        const existing = recentNetworkUrls.get(canonicalUrl);
+        if (existing && event.timestamp - existing.timestamp < 30000) {
+          // 30 second window
+          isDuplicate = true;
+          const timeSince = event.timestamp - existing.timestamp;
+          const timeLabel = formatMermaidDuration(timeSince);
+          duplicateInfo = `⚠️ Already fetched ${timeLabel} ago`;
+          recentNetworkUrls.set(canonicalUrl, {
+            timestamp: event.timestamp,
+            count: existing.count + 1
+          });
+        } else {
+          recentNetworkUrls.set(canonicalUrl, {
+            timestamp: event.timestamp,
+            count: 1
+          });
+        }
+      }
+    }
+
+    // Wrap duplicates or errors in highlighted rect
+    if (isDuplicate) {
+      lines.push("    rect rgb(255, 245, 230)");
+      lines.push(`        Note over App,API: ${duplicateInfo}`);
+      for (const msg of messages) {
+        lines.push(`        ${msg}`);
+      }
+      for (const note of notes) {
+        lines.push(`        ${note}`);
+      }
+      lines.push("    end");
+    } else if (event.status === "error") {
+      lines.push("    rect rgb(255, 235, 235)");
+      for (const msg of messages) {
+        lines.push(`        ${msg}`);
+      }
+      for (const note of notes) {
+        lines.push(`        ${note}`);
+      }
+      lines.push("    end");
+    } else {
+      for (const msg of messages) {
+        lines.push(`    ${msg}`);
+      }
+      for (const note of notes) {
+        lines.push(`    ${note}`);
+      }
+    }
+  }
+
+  // Add note about skipped internal events if any
+  if (skippedCount > 0) {
+    lines.push("");
+    lines.push(`    Note over App: ${skippedCount} internal events hidden`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Generate export based on settings format
  */
@@ -1088,6 +1863,8 @@ function generateExport(events, settings) {
       return generateJsonExport(events, settings);
     case "plaintext":
       return generatePlaintextExport(events, settings);
+    case "mermaid":
+      return generateMermaidExport(events, settings);
     default:
       return generateMarkdownExport(events, settings);
   }