fixdog 0.0.1

package/src/element-detector.ts

@@ -0,0 +1,186 @@
+/**
+ * Element detector - handles Alt+click detection and source resolution using Bippy
+ */
+
+import {
+  getSourceFromElement,
+  getComponentNameFromFiber,
+  getFiberFromHostInstance,
+} from "./instrument";
+import { isSourceFile } from "./source-resolver";
+import type { ElementDetectorOptions, SourceLocation } from "./types";
+
+let detectorCleanup: (() => void) | null = null;
+let isSetup = false;
+
+/**
+ * Setup element detection with Alt+click (or other modifier)
+ */
+export function setupElementDetector(
+  options: ElementDetectorOptions
+): () => void {
+  const { onElementSelected, modifier = "alt" } = options;
+
+  // Cleanup any existing detector
+  if (detectorCleanup) {
+    detectorCleanup();
+  }
+
+  isSetup = true;
+
+  const handleClick = async (event: MouseEvent) => {
+    // Check if modifier key is pressed
+    const modifierPressed =
+      (modifier === "alt" && event.altKey) ||
+      (modifier === "ctrl" && event.ctrlKey) ||
+      (modifier === "meta" && event.metaKey) ||
+      (modifier === "shift" && event.shiftKey);
+
+    if (!modifierPressed) return;
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    const target = event.target as Element;
+
+    try {
+      // Get source location using Bippy
+      const source = await getSourceFromElement(target);
+
+      if (source && source.fileName && isSourceFile(source.fileName)) {
+        // Get component name
+        const fiber = getFiberFromHostInstance(target);
+        const componentName = fiber
+          ? getComponentNameFromFiber(fiber)
+          : "Unknown";
+
+        const enrichedSource: SourceLocation = {
+          ...source,
+          functionName: source.functionName || componentName,
+        };
+
+        onElementSelected(enrichedSource, target);
+      } else {
+        console.info(
+          "[UiDog Next] Could not find source for element. Falling back to DOM snapshot (likely server component or library code)."
+        );
+        onElementSelected(null, target);
+      }
+    } catch (error) {
+      console.warn("[UiDog Next] Error detecting element source:", error);
+    }
+  };
+
+  // Handle mouse movement for hover highlighting (optional enhancement)
+  const handleMouseMove = (event: MouseEvent) => {
+    // Check if modifier key is pressed
+    const modifierPressed =
+      (modifier === "alt" && event.altKey) ||
+      (modifier === "ctrl" && event.ctrlKey) ||
+      (modifier === "meta" && event.metaKey) ||
+      (modifier === "shift" && event.shiftKey);
+
+    if (!modifierPressed) {
+      removeHighlight();
+      return;
+    }
+
+    const target = event.target as Element;
+    highlightElement(target);
+  };
+
+  // Handle key up to remove highlight when modifier is released
+  const handleKeyUp = (event: KeyboardEvent) => {
+    const relevantKey =
+      (modifier === "alt" && event.key === "Alt") ||
+      (modifier === "ctrl" && event.key === "Control") ||
+      (modifier === "meta" && event.key === "Meta") ||
+      (modifier === "shift" && event.key === "Shift");
+
+    if (relevantKey) {
+      removeHighlight();
+    }
+  };
+
+  // Use capture phase to intercept before other handlers
+  document.addEventListener("click", handleClick, true);
+  document.addEventListener("mousemove", handleMouseMove, true);
+  document.addEventListener("keyup", handleKeyUp, true);
+
+  detectorCleanup = () => {
+    document.removeEventListener("click", handleClick, true);
+    document.removeEventListener("mousemove", handleMouseMove, true);
+    document.removeEventListener("keyup", handleKeyUp, true);
+    removeHighlight();
+    isSetup = false;
+  };
+
+  return detectorCleanup;
+}
+
+// Highlight state
+let currentHighlight: HTMLElement | null = null;
+let highlightOverlay: HTMLElement | null = null;
+
+/**
+ * Highlight an element on hover when modifier is pressed
+ */
+function highlightElement(element: Element): void {
+  // Don't highlight our own overlay
+  if (element === highlightOverlay || highlightOverlay?.contains(element)) {
+    return;
+  }
+
+  // Create overlay if it doesn't exist
+  if (!highlightOverlay) {
+    highlightOverlay = document.createElement("div");
+    highlightOverlay.id = "uidog-highlight-overlay";
+    highlightOverlay.style.cssText = `
+      position: fixed;
+      pointer-events: none;
+      background: rgba(59, 130, 246, 0.2);
+      border: 2px solid rgba(59, 130, 246, 0.8);
+      border-radius: 4px;
+      z-index: 999998;
+      transition: all 0.1s ease-out;
+    `;
+    document.body.appendChild(highlightOverlay);
+  }
+
+  // Update position
+  const rect = element.getBoundingClientRect();
+  highlightOverlay.style.top = `${rect.top}px`;
+  highlightOverlay.style.left = `${rect.left}px`;
+  highlightOverlay.style.width = `${rect.width}px`;
+  highlightOverlay.style.height = `${rect.height}px`;
+  highlightOverlay.style.display = "block";
+
+  currentHighlight = element as HTMLElement;
+}
+
+/**
+ * Remove highlight overlay
+ */
+function removeHighlight(): void {
+  if (highlightOverlay) {
+    highlightOverlay.style.display = "none";
+  }
+  currentHighlight = null;
+}
+
+/**
+ * Check if element detector is set up
+ */
+export function isElementDetectorSetup(): boolean {
+  return isSetup;
+}
+
+/**
+ * Cleanup element detector
+ */
+export function cleanupElementDetector(): void {
+  if (detectorCleanup) {
+    detectorCleanup();
+    detectorCleanup = null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * UiDog SDK for Next.js - Main entry point
+ *
+ * Uses Bippy to hook into React's internals for element source detection,
+ * providing a seamless developer experience for inspecting component locations.
+ */
+
+import { setupBippyInstrumentation } from "./instrument";
+import {
+  setupElementDetector,
+  cleanupElementDetector,
+} from "./element-detector";
+import {
+  initializeSidebar,
+  openSidebar,
+  closeSidebar,
+  cleanupSidebar,
+} from "./sidebar-initializer";
+import {
+  buildEditorUrl,
+  normalizeFileName,
+  getShortFileName,
+} from "./source-resolver";
+import type {
+  UiDogNextOptions,
+  SourceLocation,
+  ElementInfo,
+  EditorType,
+} from "./types";
+
+let isInitialized = false;
+
+/**
+ * Initialize UiDog for Next.js
+ *
+ * This function sets up Bippy instrumentation, element detection, and the sidebar UI.
+ * It should be called early in your application's lifecycle, ideally via
+ * instrumentation-client.ts (Next.js 15.3+) or at the top of _app.tsx.
+ */
+export function initializeUiDogNext(options: UiDogNextOptions = {}): void {
+  if (typeof window === "undefined") return;
+  if (isInitialized) {
+    console.warn("[UiDog Next] Already initialized");
+    return;
+  }
+
+  // Check if in development mode
+  if (process.env.NODE_ENV === "production") {
+    console.warn(
+      "[UiDog Next] Running in production mode. Element source detection may not work as _debugSource is stripped in production builds."
+    );
+  }
+
+  const {
+    editor = "cursor",
+    projectPath = "",
+    modifier = "alt",
+    enableSidebar = true,
+    apiEndpoint = "https://api.ui.dog",
+  } = options;
+
+  isInitialized = true;
+  window.__UIDOG_NEXT_INITIALIZED__ = true;
+
+  // Setup Bippy instrumentation (hooks into React DevTools API)
+  setupBippyInstrumentation();
+
+  // Initialize sidebar if enabled
+  if (enableSidebar) {
+    initializeSidebar({ apiEndpoint });
+  }
+
+  // Setup element detection (Alt+click to select elements)
+  setupElementDetector({
+    modifier,
+    onElementSelected: (source: SourceLocation | null, element: Element) => {
+      const rect = element.getBoundingClientRect
+        ? element.getBoundingClientRect()
+        : null;
+
+      const buildDomSnapshot = () => {
+        const outerHTML = element.outerHTML || "";
+        const text = (element.textContent || "").trim();
+        const attributes: Record<string, string> = {};
+
+        Array.from(element.attributes || []).forEach((attr) => {
+          attributes[attr.name] = attr.value;
+        });
+
+        return {
+          outerHTML:
+            outerHTML.length > 4000
+              ? `${outerHTML.slice(0, 4000)}…`
+              : outerHTML,
+          text: text.length > 1000 ? `${text.slice(0, 1000)}…` : text,
+          attributes,
+        };
+      };
+
+      if (source) {
+        const editorUrl = buildEditorUrl(source, editor, projectPath);
+
+        console.info(
+          "[UiDog Next] Source detected:",
+          normalizeFileName(source.fileName),
+          "line",
+          source.lineNumber,
+          "column",
+          source.columnNumber
+        );
+
+        if (enableSidebar) {
+          const elementInfo: ElementInfo = {
+            kind: "source",
+            componentName: source.functionName || "Unknown",
+            filePath: normalizeFileName(source.fileName),
+            line: source.lineNumber,
+            column: source.columnNumber,
+            box: rect
+              ? {
+                  x: rect.x,
+                  y: rect.y,
+                  width: rect.width,
+                  height: rect.height,
+                }
+              : undefined,
+          };
+
+          openSidebar(elementInfo, editorUrl);
+        } else {
+          console.log("[UiDog Next] Element selected:");
+          console.log("  Component:", source.functionName || "Unknown");
+          console.log("  File:", source.fileName);
+          console.log("  Line:", source.lineNumber);
+          console.log("  Column:", source.columnNumber);
+          console.log("  Editor URL:", editorUrl);
+        }
+      } else {
+        const domSnapshot = buildDomSnapshot();
+
+        console.info("[UiDog Next] DOM snapshot (no source):", {
+          outerHTML: domSnapshot.outerHTML,
+          text: domSnapshot.text,
+          attributes: domSnapshot.attributes,
+          box: rect
+            ? {
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+              }
+            : undefined,
+        });
+
+        const elementInfo: ElementInfo = {
+          kind: "dom",
+          componentName: "Server-rendered element",
+          domSnapshot,
+          box: rect
+            ? {
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+              }
+            : undefined,
+        };
+
+        if (enableSidebar) {
+          openSidebar(elementInfo, "");
+        } else {
+          console.log("[UiDog Next] Element selected (DOM snapshot):");
+          console.log("  outerHTML:", domSnapshot.outerHTML);
+          console.log("  text:", domSnapshot.text);
+        }
+      }
+    },
+  });
+
+  console.log(
+    `[UiDog Next] Initialized (${modifier}+click to select elements)`
+  );
+}
+
+/**
+ * Cleanup UiDog - removes all event listeners and UI
+ */
+export function cleanupUiDogNext(): void {
+  cleanupElementDetector();
+  cleanupSidebar();
+  isInitialized = false;
+
+  if (typeof window !== "undefined") {
+    window.__UIDOG_NEXT_INITIALIZED__ = false;
+  }
+}
+
+/**
+ * Check if UiDog is initialized
+ */
+export function isUiDogNextInitialized(): boolean {
+  return isInitialized;
+}
+
+// Re-export types and utilities
+export type {
+  UiDogNextOptions,
+  SourceLocation,
+  ElementInfo,
+  EditorType,
+  SidebarConfig,
+  EditRequest,
+  EditResponse,
+} from "./types";
+
+export {
+  buildEditorUrl,
+  normalizeFileName,
+  getShortFileName,
+} from "./source-resolver";
+
+export { openSidebar, closeSidebar } from "./sidebar-initializer";
+
+export {
+  setupBippyInstrumentation,
+  getSourceFromElement,
+  getComponentNameFromFiber,
+} from "./instrument";

package/src/instrument.ts

@@ -0,0 +1,171 @@
+/**
+ * Bippy instrumentation setup for React fiber inspection
+ *
+ * Bippy hooks into React's DevTools API (window.__REACT_DEVTOOLS_GLOBAL_HOOK__)
+ * to intercept fiber tree data and extract source location information.
+ */
+
+import {
+  instrument,
+  secure,
+  isCompositeFiber,
+  isHostFiber,
+  traverseFiber,
+  getDisplayName,
+  getFiberFromHostInstance,
+} from "bippy";
+import { getSource } from "bippy/source";
+import type { SourceLocation } from "./types";
+
+let isInstrumented = false;
+
+/**
+ * Setup Bippy instrumentation to hook into React's internals
+ * This must be called BEFORE React loads (via instrumentation-client.ts)
+ */
+export function setupBippyInstrumentation(): void {
+  if (isInstrumented) return;
+  if (typeof window === "undefined") return;
+
+  isInstrumented = true;
+
+  instrument(
+    secure({
+      onCommitFiberRoot: (_rendererID, _fiberRoot) => {
+        // Called when React commits a render
+        // We can use this for additional tracking if needed
+      },
+    })
+  );
+}
+
+/**
+ * Get source location from a DOM element by traversing its React fiber
+ */
+export async function getSourceFromElement(
+  element: Element
+): Promise<SourceLocation | null> {
+  try {
+    // Get the fiber associated with this DOM element
+    const fiber = getFiberFromHostInstance(element);
+
+    if (!fiber) {
+      return null;
+    }
+
+    // Try to get source from the fiber
+    const source = await getSource(fiber);
+
+    if (source && source.fileName) {
+      // Filter out node_modules and internal files
+      if (
+        source.fileName.includes("node_modules") ||
+        source.fileName.includes("react-dom") ||
+        source.fileName.includes("react/")
+      ) {
+        // Try parent fibers to find user code
+        return await findUserSourceFromFiber(fiber);
+      }
+
+      return {
+        fileName: source.fileName,
+        lineNumber: source.lineNumber ?? 1,
+        columnNumber: source.columnNumber ?? 1,
+        functionName: source.functionName ?? undefined,
+      };
+    }
+
+    // Fallback: traverse up the fiber tree to find source
+    return await findUserSourceFromFiber(fiber);
+  } catch (error) {
+    console.warn("[UiDog Next] Error getting source from element:", error);
+    return null;
+  }
+}
+
+/**
+ * Traverse up the fiber tree to find the first user-code source
+ */
+async function findUserSourceFromFiber(
+  startFiber: any
+): Promise<SourceLocation | null> {
+  let result: SourceLocation | null = null;
+
+  // Traverse upward through the fiber tree
+  traverseFiber(
+    startFiber,
+    async (fiber) => {
+      // Only check composite fibers (components, not host elements)
+      if (isCompositeFiber(fiber)) {
+        try {
+          const source = await getSource(fiber);
+
+          if (source && source.fileName) {
+            // Skip internal/library code
+            if (
+              !source.fileName.includes("node_modules") &&
+              !source.fileName.includes("react-dom") &&
+              !source.fileName.includes("react/")
+            ) {
+              result = {
+                fileName: source.fileName,
+                lineNumber: source.lineNumber ?? 1,
+                columnNumber: source.columnNumber ?? 1,
+                functionName: source.functionName ?? getDisplayName(fiber) ?? undefined,
+              };
+              return true; // Stop traversal
+            }
+          }
+        } catch {
+          // Continue to next fiber
+        }
+      }
+      return false; // Continue traversal
+    },
+    true // Traverse upward (toward root)
+  );
+
+  return result;
+}
+
+/**
+ * Get component name from a fiber
+ */
+export function getComponentNameFromFiber(fiber: any): string {
+  if (!fiber) return "Unknown";
+
+  // Try to get display name directly
+  const displayName = getDisplayName(fiber);
+  if (displayName && displayName !== "Unknown") {
+    return displayName;
+  }
+
+  // Traverse up to find the nearest named component
+  let componentName = "Unknown";
+
+  traverseFiber(
+    fiber,
+    (f) => {
+      if (isCompositeFiber(f)) {
+        const name = getDisplayName(f);
+        if (name && name !== "Unknown") {
+          componentName = name;
+          return true; // Stop traversal
+        }
+      }
+      return false;
+    },
+    true // Traverse upward
+  );
+
+  return componentName;
+}
+
+// Re-export useful bippy utilities
+export {
+  isCompositeFiber,
+  isHostFiber,
+  traverseFiber,
+  getDisplayName,
+  getFiberFromHostInstance,
+};