sonance-brand-mcp 1.3.111 → 1.3.113

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

@@ -0,0 +1,212 @@
+"use client";
+
+/**
+ * Content-based hashing utilities for generating stable element IDs
+ *
+ * Instead of sequential IDs (text-0, logo-1) that change on re-render,
+ * we generate IDs based on element content that persist across page loads.
+ */
+
+/**
+ * Fast hash function (djb2 algorithm)
+ * Produces a short, consistent hash string from any input
+ */
+export function hashString(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+  }
+  // Convert to hex and take last 8 chars for brevity
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Get a stable DOM path for an element (up to 3 levels)
+ * This helps differentiate elements with similar content in different locations
+ */
+function getDOMPath(element: Element, maxDepth: number = 3): string {
+  const path: string[] = [];
+  let current: Element | null = element;
+  let depth = 0;
+
+  while (current && current !== document.body && depth < maxDepth) {
+    const tag = current.tagName.toLowerCase();
+    const parent: Element | null = current.parentElement;
+
+    if (parent) {
+      // Get index among siblings of same type
+      const siblings = Array.from(parent.children).filter(
+        (child) => child.tagName === current!.tagName
+      );
+      const index = siblings.indexOf(current);
+      path.unshift(`${tag}[${index}]`);
+    } else {
+      path.unshift(tag);
+    }
+
+    current = parent;
+    depth++;
+  }
+
+  return path.join(">");
+}
+
+/**
+ * Generate a stable ID for text elements
+ * Based on: tagName + truncated textContent + DOM path
+ */
+export function generateTextElementId(element: Element): string {
+  const tagName = element.tagName.toLowerCase();
+  const textContent = (element.textContent || "").trim().substring(0, 50);
+  const domPath = getDOMPath(element);
+
+  const signature = `text:${tagName}:${textContent}:${domPath}`;
+  return `text-${hashString(signature)}`;
+}
+
+/**
+ * Generate a stable ID for image elements
+ * Based on: src (normalized) + alt + natural dimensions
+ */
+export function generateImageElementId(img: HTMLImageElement): string {
+  // Normalize src by removing query params and getting filename
+  const src = img.src || img.getAttribute("src") || "";
+  const srcPath = src.split("?")[0].split("/").pop() || src;
+  const alt = img.alt || "";
+  const dimensions = `${img.naturalWidth || 0}x${img.naturalHeight || 0}`;
+
+  const signature = `img:${srcPath}:${alt}:${dimensions}`;
+  return `logo-${hashString(signature)}`;
+}
+
+/**
+ * Generate a stable ID for component elements
+ * Based on: component name + variant styles + DOM path
+ */
+export function generateComponentId(element: Element): string {
+  const name = element.getAttribute("data-sonance-name") || element.tagName.toLowerCase();
+  const className = element.className?.toString() || "";
+  const domPath = getDOMPath(element);
+
+  const signature = `comp:${name}:${className}:${domPath}`;
+  return `comp-${hashString(signature)}`;
+}
+
+/**
+ * Generate a variant ID based on computed styles
+ * This groups visually identical components together
+ */
+export function generateVariantId(element: Element): string {
+  const className = element.className?.toString() || "";
+  const computed = window.getComputedStyle(element);
+
+  const styleSignature = [
+    className,
+    computed.backgroundColor,
+    computed.borderColor,
+    computed.borderRadius,
+    computed.color,
+  ].join("|");
+
+  return hashString(styleSignature);
+}
+
+/**
+ * Migration utilities for backwards compatibility with old sequential IDs
+ */
+
+interface LegacyIdMapping {
+  oldId: string;
+  newId: string;
+  selector: string;
+  textContent?: string;
+}
+
+/**
+ * Migrate old sequential IDs to new content-based IDs
+ * Returns a mapping that can be used to update localStorage entries
+ */
+export function migrateLegacyIds(
+  type: "text" | "logo",
+  oldOverrides: Record<string, unknown>
+): { migrated: Record<string, unknown>; mappings: LegacyIdMapping[] } {
+  const migrated: Record<string, unknown> = {};
+  const mappings: LegacyIdMapping[] = [];
+
+  // Pattern for old sequential IDs
+  const legacyPattern = type === "text" ? /^text-\d+$/ : /^logo-\d+$/;
+
+  for (const [oldId, value] of Object.entries(oldOverrides)) {
+    if (legacyPattern.test(oldId)) {
+      // Try to find the element and generate new ID
+      const selector = `[data-sonance-${type}-id="${oldId}"]`;
+      const element = document.querySelector(selector);
+
+      if (element) {
+        const newId = type === "text"
+          ? generateTextElementId(element)
+          : generateImageElementId(element as HTMLImageElement);
+
+        migrated[newId] = value;
+        mappings.push({
+          oldId,
+          newId,
+          selector,
+          textContent: element.textContent?.substring(0, 50),
+        });
+
+        // Update the element's data attribute to use new ID
+        element.setAttribute(`data-sonance-${type}-id`, newId);
+      } else {
+        // Element not found - keep old ID for now
+        migrated[oldId] = value;
+      }
+    } else {
+      // Already using new format or unknown format - keep as is
+      migrated[oldId] = value;
+    }
+  }
+
+  return { migrated, mappings };
+}
+
+/**
+ * Check if an ID is in the legacy sequential format
+ */
+export function isLegacyId(id: string): boolean {
+  return /^(text|logo)-\d+$/.test(id);
+}
+
+/**
+ * Storage key constants for migration tracking
+ */
+export const MIGRATION_STORAGE_KEY = "sonance-id-migration-complete";
+export const MIGRATION_VERSION = 1;
+
+/**
+ * Check if migration has already been performed
+ */
+export function isMigrationComplete(): boolean {
+  try {
+    const stored = localStorage.getItem(MIGRATION_STORAGE_KEY);
+    if (!stored) return false;
+    const { version } = JSON.parse(stored);
+    return version >= MIGRATION_VERSION;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark migration as complete
+ */
+export function markMigrationComplete(): void {
+  try {
+    localStorage.setItem(
+      MIGRATION_STORAGE_KEY,
+      JSON.stringify({ version: MIGRATION_VERSION, timestamp: Date.now() })
+    );
+  } catch {
+    // Ignore storage errors
+  }
+}

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 };