sonance-brand-mcp 1.3.110 → 1.3.112

package/dist/assets/dev-tools/hooks/useElementScanner.ts

@@ -0,0 +1,398 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { DetectedElement, ElementFilters, OriginalLogoState, OriginalTextState } from "../types";
+import { getActiveModalContent } from "../utils";
+import { detectComponents } from "./useComponentDetection";
+import { detectImages, extractLogoName } from "./useImageDetection";
+import { detectTextElements } from "./useTextDetection";
+import {
+  migrateLegacyIds,
+  isMigrationComplete,
+  markMigrationComplete,
+} from "./useContentHash";
+
+/**
+ * Scanner configuration
+ */
+export interface ElementScannerOptions {
+  /** Whether scanning is enabled */
+  enabled: boolean;
+  /** Element type filters */
+  filters: ElementFilters;
+  /** Whether inspector highlighting is active (affects text detection) */
+  inspectorEnabled?: boolean;
+}
+
+/**
+ * Scanner result
+ */
+export interface ElementScannerResult {
+  /** All detected elements */
+  elements: DetectedElement[];
+  /** Original logo states (for reset functionality) */
+  originalLogoStates: Record<string, OriginalLogoState>;
+  /** Original text states (for reset functionality) */
+  originalTextStates: Record<string, OriginalTextState>;
+  /** Trigger a manual re-scan */
+  rescan: () => void;
+  /** Reset all original states */
+  resetStates: () => void;
+}
+
+/**
+ * Debounce delay for mutation observer (ms)
+ */
+const MUTATION_DEBOUNCE_MS = 100;
+
+/**
+ * Throttle limit for scans per second
+ */
+const MAX_SCANS_PER_SECOND = 5;
+
+/**
+ * Helper: Check if element is inside a scroll container and clip rect to visible bounds
+ */
+function getVisibleRect(el: Element, rect: DOMRect): DOMRect | null {
+  const scrollParent = el.closest("aside, nav, [data-sidebar]");
+
+  if (scrollParent) {
+    const parentRect = scrollParent.getBoundingClientRect();
+
+    // Check if element is fully outside the scroll container
+    if (
+      rect.bottom < parentRect.top ||
+      rect.top > parentRect.bottom ||
+      rect.right < parentRect.left ||
+      rect.left > parentRect.right
+    ) {
+      return null;
+    }
+
+    // Clip the rect to parent's visible bounds
+    const clippedTop = Math.max(rect.top, parentRect.top);
+    const clippedBottom = Math.min(rect.bottom, parentRect.bottom);
+    const clippedLeft = Math.max(rect.left, parentRect.left);
+    const clippedRight = Math.min(rect.right, parentRect.right);
+
+    // If clipped area is too small, skip it
+    if (clippedBottom - clippedTop < 10 || clippedRight - clippedLeft < 10) {
+      return null;
+    }
+
+    return new DOMRect(
+      clippedLeft,
+      clippedTop,
+      clippedRight - clippedLeft,
+      clippedBottom - clippedTop
+    );
+  }
+
+  return rect;
+}
+
+/**
+ * Helper: Check if element is in the active layer (not behind a modal)
+ */
+function createActiveLayerChecker(): (el: Element) => boolean {
+  const activeModalContent = getActiveModalContent();
+
+  return (el: Element): boolean => {
+    // Always exclude DevTools panel
+    if (el.closest("[data-sonance-devtools]")) return false;
+
+    // If a modal is active, only include elements inside the modal
+    if (activeModalContent) {
+      return activeModalContent.contains(el) || el === activeModalContent;
+    }
+
+    return true;
+  };
+}
+
+/**
+ * Perform a one-time migration of legacy sequential IDs in localStorage
+ */
+function performLegacyMigration(): void {
+  if (isMigrationComplete()) return;
+
+  try {
+    // Migrate text overrides
+    const textOverridesRaw = localStorage.getItem("sonance-text-overrides");
+    if (textOverridesRaw) {
+      const textOverrides = JSON.parse(textOverridesRaw);
+      const { migrated, mappings } = migrateLegacyIds("text", textOverrides);
+
+      if (mappings.length > 0) {
+        console.log("[Sonance] Migrated text element IDs:", mappings);
+        localStorage.setItem("sonance-text-overrides", JSON.stringify(migrated));
+      }
+    }
+
+    // Migrate logo configs
+    const logoConfigsRaw = localStorage.getItem("sonance-logo-configs");
+    if (logoConfigsRaw) {
+      const logoConfigs = JSON.parse(logoConfigsRaw);
+      const { migrated, mappings } = migrateLegacyIds("logo", logoConfigs);
+
+      if (mappings.length > 0) {
+        console.log("[Sonance] Migrated logo element IDs:", mappings);
+        localStorage.setItem("sonance-logo-configs", JSON.stringify(migrated));
+      }
+    }
+
+    markMigrationComplete();
+  } catch (e) {
+    console.warn("[Sonance] Migration failed:", e);
+  }
+}
+
+/**
+ * Main element scanner hook
+ *
+ * Uses MutationObserver for efficient change detection instead of
+ * continuous requestAnimationFrame polling.
+ */
+export function useElementScanner(options: ElementScannerOptions): ElementScannerResult {
+  const { enabled, filters, inspectorEnabled = false } = options;
+
+  // State
+  const [elements, setElements] = useState<DetectedElement[]>([]);
+
+  // Refs for original states (avoid re-renders on state changes)
+  const originalLogoStatesRef = useRef<Record<string, OriginalLogoState>>({});
+  const originalTextStatesRef = useRef<Record<string, OriginalTextState>>({});
+
+  // Throttling refs
+  const lastScanTimeRef = useRef<number>(0);
+  const pendingScanRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const rafIdRef = useRef<number | null>(null);
+
+  // Mounted ref for cleanup
+  const mountedRef = useRef(true);
+
+  /**
+   * Core scan function - detects all elements based on current filters
+   */
+  const performScan = useCallback(() => {
+    if (!mountedRef.current) return;
+
+    const now = Date.now();
+    const timeSinceLastScan = now - lastScanTimeRef.current;
+    const minInterval = 1000 / MAX_SCANS_PER_SECOND;
+
+    // Throttle if scanning too frequently
+    if (timeSinceLastScan < minInterval) {
+      if (!pendingScanRef.current) {
+        pendingScanRef.current = setTimeout(() => {
+          pendingScanRef.current = null;
+          performScan();
+        }, minInterval - timeSinceLastScan);
+      }
+      return;
+    }
+
+    lastScanTimeRef.current = now;
+
+    const allElements: DetectedElement[] = [];
+    const isInActiveLayer = createActiveLayerChecker();
+
+    // Scan components
+    if (filters.components) {
+      const componentConfig = {
+        includeModals: true,
+        isInActiveLayer,
+        getVisibleRect,
+      };
+      const componentElements = detectComponents(componentConfig);
+      allElements.push(...componentElements);
+    }
+
+    // Scan images/logos
+    if (filters.images) {
+      const imageConfig = {
+        isInActiveLayer,
+        existingOriginalStates: originalLogoStatesRef.current,
+      };
+      const { elements: imageElements, originalStates: newLogoStates } = detectImages(imageConfig);
+      allElements.push(...imageElements);
+      originalLogoStatesRef.current = newLogoStates;
+    }
+
+    // Scan text elements (only when inspector is enabled)
+    if (filters.text && inspectorEnabled) {
+      const textConfig = {
+        isInActiveLayer,
+        existingOriginalStates: originalTextStatesRef.current,
+      };
+      const { elements: textElements, originalStates: newTextStates } = detectTextElements(textConfig);
+      allElements.push(...textElements);
+      originalTextStatesRef.current = newTextStates;
+    }
+
+    setElements(allElements);
+  }, [filters, inspectorEnabled]);
+
+  /**
+   * Position update function - uses RAF for smooth position tracking
+   * Only updates rects, doesn't re-detect elements
+   */
+  const updatePositions = useCallback(() => {
+    if (!mountedRef.current || !enabled) return;
+
+    setElements((prevElements) => {
+      if (prevElements.length === 0) return prevElements;
+
+      let hasChanges = false;
+      const updated = prevElements.map((el) => {
+        // Find the actual DOM element
+        let domEl: Element | null = null;
+
+        if (el.type === "logo" && el.logoId) {
+          domEl = document.querySelector(`[data-sonance-logo-id="${el.logoId}"]`);
+        } else if (el.type === "text" && el.textId) {
+          domEl = document.querySelector(`[data-sonance-text-id="${el.textId}"]`);
+        } else if (el.type === "component" && el.variantId) {
+          domEl = document.querySelector(`[data-sonance-variant="${el.variantId}"]`);
+        }
+
+        if (!domEl) return el;
+
+        const newRect = domEl.getBoundingClientRect();
+        const visibleRect = getVisibleRect(domEl, newRect);
+
+        if (!visibleRect) {
+          // Element is no longer visible
+          hasChanges = true;
+          return null;
+        }
+
+        // Check if position actually changed
+        if (
+          Math.abs(el.rect.left - visibleRect.left) > 1 ||
+          Math.abs(el.rect.top - visibleRect.top) > 1 ||
+          Math.abs(el.rect.width - visibleRect.width) > 1 ||
+          Math.abs(el.rect.height - visibleRect.height) > 1
+        ) {
+          hasChanges = true;
+          return { ...el, rect: visibleRect };
+        }
+
+        return el;
+      }).filter((el): el is DetectedElement => el !== null);
+
+      return hasChanges ? updated : prevElements;
+    });
+  }, [enabled]);
+
+  /**
+   * Rescan trigger (exposed to parent)
+   */
+  const rescan = useCallback(() => {
+    performScan();
+  }, [performScan]);
+
+  /**
+   * Reset all original states
+   */
+  const resetStates = useCallback(() => {
+    originalLogoStatesRef.current = {};
+    originalTextStatesRef.current = {};
+  }, []);
+
+  // Perform legacy ID migration on mount
+  useEffect(() => {
+    performLegacyMigration();
+  }, []);
+
+  // Main effect: Set up MutationObserver and position tracking
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (!enabled) {
+      setElements([]);
+      return;
+    }
+
+    // Initial scan
+    performScan();
+
+    // Set up MutationObserver for DOM changes
+    let debounceTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    const observer = new MutationObserver((mutations) => {
+      // Skip mutations inside DevTools
+      const hasRelevantMutation = mutations.some((mutation) => {
+        const target = mutation.target as Element;
+        return !target.closest?.("[data-sonance-devtools]");
+      });
+
+      if (!hasRelevantMutation) return;
+
+      // Debounce to batch rapid changes
+      if (debounceTimeout) {
+        clearTimeout(debounceTimeout);
+      }
+
+      debounceTimeout = setTimeout(() => {
+        debounceTimeout = null;
+        performScan();
+      }, MUTATION_DEBOUNCE_MS);
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["class", "style", "src", "data-state"],
+    });
+
+    // Set up scroll/resize listeners for position updates
+    const handlePositionUpdate = () => {
+      if (rafIdRef.current) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+      rafIdRef.current = requestAnimationFrame(updatePositions);
+    };
+
+    window.addEventListener("scroll", handlePositionUpdate, true);
+    window.addEventListener("resize", handlePositionUpdate);
+
+    // Cleanup
+    return () => {
+      mountedRef.current = false;
+      observer.disconnect();
+
+      if (debounceTimeout) {
+        clearTimeout(debounceTimeout);
+      }
+      if (pendingScanRef.current) {
+        clearTimeout(pendingScanRef.current);
+      }
+      if (rafIdRef.current) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+
+      window.removeEventListener("scroll", handlePositionUpdate, true);
+      window.removeEventListener("resize", handlePositionUpdate);
+    };
+  }, [enabled, performScan, updatePositions]);
+
+  // Re-scan when filters change
+  useEffect(() => {
+    if (enabled) {
+      performScan();
+    }
+  }, [enabled, filters, inspectorEnabled, performScan]);
+
+  return {
+    elements,
+    originalLogoStates: originalLogoStatesRef.current,
+    originalTextStates: originalTextStatesRef.current,
+    rescan,
+    resetStates,
+  };
+}
+
+// Re-export utilities for use in other components
+export { extractLogoName };

package/dist/assets/dev-tools/hooks/useImageDetection.ts

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useRef } from "react";
+import { DetectedElement, OriginalLogoState } from "../types";
+import { generateImageElementId, isLegacyId } from "./useContentHash";
+
+/**
+ * Image detection configuration
+ */
+export interface ImageDetectionConfig {
+  /** Callback to check if element is in active layer */
+  isInActiveLayer: (el: Element) => boolean;
+  /** Current original states (for preserving existing state) */
+  existingOriginalStates?: Record<string, OriginalLogoState>;
+}
+
+/**
+ * Image detection result
+ */
+export interface ImageDetectionResult {
+  elements: DetectedElement[];
+  originalStates: Record<string, OriginalLogoState>;
+}
+
+/**
+ * Extract logo name from image src
+ * Returns name if src contains "logo", null otherwise
+ */
+export function extractLogoName(src: string): string | null {
+  if (!src) return null;
+
+  const lowerSrc = src.toLowerCase();
+  if (!lowerSrc.includes("logo")) return null;
+
+  // Extract filename without extension
+  const filename = src.split("/").pop()?.split("?")[0] || "";
+  const nameWithoutExt = filename.replace(/\.[^/.]+$/, "");
+
+  // Clean up the name
+  return nameWithoutExt
+    .replace(/[-_]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Detect images/logos on the page
+ * Identifies logo images and tracks their original state
+ */
+export function detectImages(config: ImageDetectionConfig): ImageDetectionResult {
+  const { isInActiveLayer, existingOriginalStates = {} } = config;
+  const detected: DetectedElement[] = [];
+  const originalStates: Record<string, OriginalLogoState> = { ...existingOriginalStates };
+
+  const images = document.querySelectorAll("img");
+  images.forEach((img) => {
+    if (!isInActiveLayer(img)) return;
+
+    const src = img.src || img.getAttribute("src") || "";
+    const alt = img.alt || "";
+
+    // Check if this is a logo (src or alt contains "logo")
+    const logoName = extractLogoName(src);
+    const altContainsLogo = alt.toLowerCase().includes("logo");
+
+    if (!logoName && !altContainsLogo) return;
+
+    const rect = img.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return;
+
+    // Get or generate stable ID
+    let logoId = img.getAttribute("data-sonance-logo-id");
+
+    // Check if using legacy sequential ID and migrate if needed
+    if (logoId && isLegacyId(logoId)) {
+      const newId = generateImageElementId(img);
+      img.setAttribute("data-sonance-logo-id", newId);
+
+      // Migrate original state if exists
+      if (originalStates[logoId]) {
+        originalStates[newId] = originalStates[logoId];
+        delete originalStates[logoId];
+      }
+
+      logoId = newId;
+    }
+
+    if (!logoId) {
+      logoId = generateImageElementId(img);
+      img.setAttribute("data-sonance-logo-id", logoId);
+    }
+
+    // Store original state if not already stored
+    if (!originalStates[logoId]) {
+      const originalSrc = img.getAttribute("data-original-src") || src;
+      const originalSrcset = img.getAttribute("data-original-srcset") || img.srcset || "";
+
+      originalStates[logoId] = {
+        src: originalSrc,
+        width: img.naturalWidth || img.width,
+        height: img.naturalHeight || img.height,
+        srcset: originalSrcset || undefined,
+      };
+
+      // Store original src/srcset as data attributes for reset
+      if (!img.getAttribute("data-original-src")) {
+        img.setAttribute("data-original-src", src);
+      }
+      if (!img.getAttribute("data-original-srcset") && img.srcset) {
+        img.setAttribute("data-original-srcset", img.srcset);
+      }
+    }
+
+    const displayName = logoName || alt || "Logo";
+    const imageSrc = img.getAttribute("data-original-src") || src;
+
+    detected.push({
+      name: displayName,
+      rect,
+      type: "logo",
+      logoId,
+      imageSrc,
+    });
+  });
+
+  return { elements: detected, originalStates };
+}
+
+/**
+ * Hook for image detection
+ * Maintains original state across scans
+ */
+export function useImageDetection() {
+  const originalStatesRef = useRef<Record<string, OriginalLogoState>>({});
+
+  const detect = useCallback((config: Omit<ImageDetectionConfig, "existingOriginalStates">): ImageDetectionResult => {
+    const result = detectImages({
+      ...config,
+      existingOriginalStates: originalStatesRef.current,
+    });
+
+    // Update ref with new states
+    originalStatesRef.current = result.originalStates;
+
+    return result;
+  }, []);
+
+  const resetOriginalStates = useCallback(() => {
+    originalStatesRef.current = {};
+  }, []);
+
+  const getOriginalStates = useCallback(() => {
+    return originalStatesRef.current;
+  }, []);
+
+  return {
+    detectImages: detect,
+    resetOriginalStates,
+    getOriginalStates,
+    originalStatesRef,
+  };
+}