@designtools/next-plugin 0.1.2

package/src/codesurface.tsx

@@ -0,0 +1,452 @@
+"use client";
+
+/**
+ * <CodeSurface /> — Selection overlay component for the target app.
+ * Mounted automatically by withDesigntools() in development.
+ * Communicates with the editor UI via postMessage.
+ *
+ * Refactored from core/src/inject/selection.ts into a React component
+ * with proper lifecycle management.
+ */
+
+import { useEffect, useRef } from "react";
+
+// Overlay elements are created imperatively (not React-rendered)
+// because they need to be fixed-position overlays that don't interfere
+// with the app's React tree.
+
+export function CodeSurface() {
+  const stateRef = useRef({
+    selectionMode: false,
+    hoveredElement: null as Element | null,
+    selectedElement: null as Element | null,
+    selectedDomPath: null as string | null,
+    overlayRafId: null as number | null,
+    inlineStyleBackups: new Map<string, string>(),
+    tokenValueBackups: new Map<string, string>(),
+    tokenPreviewValues: new Map<string, string>(),
+    tokenPreviewStyle: null as HTMLStyleElement | null,
+    highlightOverlay: null as HTMLDivElement | null,
+    tooltip: null as HTMLDivElement | null,
+    selectedOverlay: null as HTMLDivElement | null,
+  });
+
+  useEffect(() => {
+    const s = stateRef.current;
+
+    // --- Create overlay DOM elements ---
+    s.highlightOverlay = document.createElement("div");
+    s.highlightOverlay.id = "tool-highlight";
+    Object.assign(s.highlightOverlay.style, {
+      position: "fixed",
+      pointerEvents: "none",
+      border: "2px solid #3b82f6",
+      backgroundColor: "rgba(59, 130, 246, 0.08)",
+      borderRadius: "2px",
+      zIndex: "99999",
+      display: "none",
+      transition: "all 0.1s ease",
+    });
+    document.body.appendChild(s.highlightOverlay);
+
+    s.tooltip = document.createElement("div");
+    s.tooltip.id = "tool-tooltip";
+    Object.assign(s.tooltip.style, {
+      position: "fixed",
+      pointerEvents: "none",
+      backgroundColor: "#1e1e2e",
+      color: "#cdd6f4",
+      padding: "3px 8px",
+      borderRadius: "4px",
+      fontSize: "11px",
+      fontFamily: "ui-monospace, monospace",
+      zIndex: "100000",
+      display: "none",
+      whiteSpace: "nowrap",
+      boxShadow: "0 2px 8px rgba(0,0,0,0.3)",
+    });
+    document.body.appendChild(s.tooltip);
+
+    s.selectedOverlay = document.createElement("div");
+    s.selectedOverlay.id = "tool-selected";
+    Object.assign(s.selectedOverlay.style, {
+      position: "fixed",
+      pointerEvents: "none",
+      border: "2px solid #f59e0b",
+      backgroundColor: "rgba(245, 158, 11, 0.06)",
+      borderRadius: "2px",
+      zIndex: "99998",
+      display: "none",
+    });
+    document.body.appendChild(s.selectedOverlay);
+
+    // --- Helpers ---
+    function getElementName(el: Element): string {
+      const slot = el.getAttribute("data-slot");
+      if (slot) return slot.charAt(0).toUpperCase() + slot.slice(1);
+      return `<${el.tagName.toLowerCase()}>`;
+    }
+
+    function getDomPath(el: Element): string {
+      // Build a pure structural path using nth-child at every level.
+      // This is stable across class changes (HMR only replaces attributes,
+      // not DOM structure) and guaranteed unique.
+      const parts: string[] = [];
+      let current: Element | null = el;
+      while (current && current !== document.body) {
+        const parent = current.parentElement;
+        if (parent) {
+          const idx = Array.from(parent.children).indexOf(current) + 1;
+          parts.unshift(`${current.tagName.toLowerCase()}:nth-child(${idx})`);
+        } else {
+          parts.unshift(current.tagName.toLowerCase());
+        }
+        current = current.parentElement;
+      }
+      return parts.join(" > ");
+    }
+
+    function positionOverlay(overlay: HTMLDivElement, rect: DOMRect) {
+      Object.assign(overlay.style, {
+        left: `${rect.left}px`,
+        top: `${rect.top}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        display: "block",
+      });
+    }
+
+    function findSelectableElement(target: Element): Element {
+      let el: Element | null = target;
+      while (el && el !== document.body) {
+        if (el.getAttribute("data-slot")) return el;
+        el = el.parentElement;
+      }
+      return target;
+    }
+
+    const relevantProps = [
+      "display", "position", "top", "right", "bottom", "left",
+      "z-index", "overflow", "overflow-x", "overflow-y",
+      "flex-direction", "flex-wrap", "justify-content", "align-items",
+      "align-self", "flex-grow", "flex-shrink", "flex-basis", "order",
+      "grid-template-columns", "grid-template-rows",
+      "gap", "row-gap", "column-gap",
+      "width", "height", "min-width", "min-height", "max-width", "max-height",
+      "margin-top", "margin-right", "margin-bottom", "margin-left",
+      "padding-top", "padding-right", "padding-bottom", "padding-left",
+      "font-family", "font-size", "font-weight", "line-height",
+      "letter-spacing", "text-align", "text-decoration", "text-transform",
+      "color", "white-space",
+      "background-color", "background-image", "background-size", "background-position",
+      "border-top-width", "border-right-width", "border-bottom-width", "border-left-width",
+      "border-style", "border-color",
+      "border-top-left-radius", "border-top-right-radius",
+      "border-bottom-right-radius", "border-bottom-left-radius",
+      "opacity", "box-shadow", "transform", "transition",
+    ];
+
+    const inheritableProps = [
+      "color", "font-family", "font-size", "font-weight", "line-height",
+      "letter-spacing", "text-align", "text-transform", "white-space",
+    ];
+
+    function extractElementData(el: Element) {
+      const computed = getComputedStyle(el);
+      const rect = el.getBoundingClientRect();
+
+      const computedStyles: Record<string, string> = {};
+      for (const prop of relevantProps) {
+        computedStyles[prop] = computed.getPropertyValue(prop);
+      }
+
+      const parentComputedStyles: Record<string, string> = {};
+      const parentEl = el.parentElement;
+      if (parentEl) {
+        const parentComputed = getComputedStyle(parentEl);
+        for (const prop of inheritableProps) {
+          parentComputedStyles[prop] = parentComputed.getPropertyValue(prop);
+        }
+      }
+
+      const attributes: Record<string, string> = {};
+      for (const attr of Array.from(el.attributes)) {
+        if (attr.name.startsWith("data-")) {
+          attributes[attr.name] = attr.value;
+        }
+      }
+
+      // Parse data-source
+      let sourceFile: string | null = null;
+      let sourceLine: number | null = null;
+      let sourceCol: number | null = null;
+
+      const dataSource = el.getAttribute("data-source");
+      if (dataSource) {
+        const lastColon = dataSource.lastIndexOf(":");
+        const secondLastColon = dataSource.lastIndexOf(":", lastColon - 1);
+        if (secondLastColon > 0) {
+          sourceFile = dataSource.slice(0, secondLastColon);
+          sourceLine = parseInt(dataSource.slice(secondLastColon + 1, lastColon), 10);
+          sourceCol = parseInt(dataSource.slice(lastColon + 1), 10);
+        }
+      }
+
+      // For component instances: read data-instance-source directly from the DOM element.
+      // The Babel transform adds this attribute to component JSX (<Button>, <Card>)
+      // and it propagates via {...props} to the rendered DOM element, carrying exact
+      // page-level coordinates of each component usage site.
+      let instanceSourceFile: string | null = null;
+      let instanceSourceLine: number | null = null;
+      let instanceSourceCol: number | null = null;
+      let componentName: string | null = null;
+
+      const instanceSource = el.getAttribute("data-instance-source");
+      if (instanceSource && el.getAttribute("data-slot")) {
+        const lc = instanceSource.lastIndexOf(":");
+        const slc = instanceSource.lastIndexOf(":", lc - 1);
+        if (slc > 0) {
+          instanceSourceFile = instanceSource.slice(0, slc);
+          instanceSourceLine = parseInt(instanceSource.slice(slc + 1, lc), 10);
+          instanceSourceCol = parseInt(instanceSource.slice(lc + 1), 10);
+        }
+
+        // Derive component name from data-slot (e.g. "card-title" -> "CardTitle")
+        const slot = el.getAttribute("data-slot") || "";
+        componentName = slot
+          .split("-")
+          .map((s: string) => s.charAt(0).toUpperCase() + s.slice(1))
+          .join("");
+      }
+
+      return {
+        tag: el.tagName.toLowerCase(),
+        className: (el.getAttribute("class") || "").trim(),
+        computedStyles,
+        parentComputedStyles,
+        boundingRect: rect,
+        domPath: getDomPath(el),
+        textContent: (el.textContent || "").trim().slice(0, 100),
+        attributes,
+        sourceFile,
+        sourceLine,
+        sourceCol,
+        instanceSourceFile,
+        instanceSourceLine,
+        instanceSourceCol,
+        componentName,
+      };
+    }
+
+    function selectElement(el: Element) {
+      s.selectedElement = el;
+      s.selectedDomPath = getDomPath(el);
+      const data = extractElementData(el);
+      if (s.selectedOverlay) {
+        positionOverlay(s.selectedOverlay, data.boundingRect);
+      }
+      startOverlayTracking();
+      window.parent.postMessage({ type: "tool:elementSelected", data }, "*");
+    }
+
+    function reselectCurrentElement() {
+      if (!s.selectedDomPath) return;
+      const el = document.querySelector(s.selectedDomPath);
+      if (el) {
+        s.selectedElement = el;
+        const data = extractElementData(el);
+        if (s.selectedOverlay) {
+          positionOverlay(s.selectedOverlay, data.boundingRect);
+        }
+        window.parent.postMessage({ type: "tool:elementSelected", data }, "*");
+      }
+    }
+
+    function startOverlayTracking() {
+      if (s.overlayRafId) cancelAnimationFrame(s.overlayRafId);
+      let lastRect = "";
+      function tick() {
+        if (s.selectedElement && s.selectedOverlay) {
+          if (!document.contains(s.selectedElement)) {
+            if (s.selectedDomPath) {
+              const newEl = document.querySelector(s.selectedDomPath);
+              if (newEl) {
+                s.selectedElement = newEl;
+                reselectCurrentElement();
+              }
+            }
+          }
+          if (s.selectedElement && document.contains(s.selectedElement)) {
+            const rect = s.selectedElement.getBoundingClientRect();
+            const key = `${rect.left},${rect.top},${rect.width},${rect.height}`;
+            if (key !== lastRect) {
+              lastRect = key;
+              positionOverlay(s.selectedOverlay!, rect);
+            }
+          }
+        }
+        s.overlayRafId = requestAnimationFrame(tick);
+      }
+      tick();
+    }
+
+    // --- Event handlers ---
+    function onMouseMove(e: MouseEvent) {
+      if (!s.selectionMode || !s.highlightOverlay || !s.tooltip) return;
+      const el = document.elementFromPoint(e.clientX, e.clientY);
+      if (!el || el === s.highlightOverlay || el === s.tooltip || el === s.selectedOverlay) return;
+      const selectable = findSelectableElement(el);
+      if (selectable === s.hoveredElement) return;
+      s.hoveredElement = selectable;
+      const rect = selectable.getBoundingClientRect();
+      positionOverlay(s.highlightOverlay, rect);
+      const name = getElementName(selectable);
+      s.tooltip.textContent = name;
+      s.tooltip.style.display = "block";
+      s.tooltip.style.left = `${rect.left}px`;
+      s.tooltip.style.top = `${Math.max(0, rect.top - 24)}px`;
+    }
+
+    function onMouseLeave() {
+      if (!s.highlightOverlay || !s.tooltip) return;
+      s.highlightOverlay.style.display = "none";
+      s.tooltip.style.display = "none";
+      s.hoveredElement = null;
+    }
+
+    function onClick(e: MouseEvent) {
+      if (!s.selectionMode) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const el = document.elementFromPoint(e.clientX, e.clientY);
+      if (!el || el === s.highlightOverlay || el === s.tooltip || el === s.selectedOverlay) return;
+      const selectable = findSelectableElement(el);
+      selectElement(selectable);
+    }
+
+    function onMessage(e: MessageEvent) {
+      const msg = e.data;
+      if (!msg || !msg.type || !msg.type.startsWith("tool:")) return;
+
+      switch (msg.type) {
+        case "tool:enterSelectionMode":
+          s.selectionMode = true;
+          document.body.style.cursor = "crosshair";
+          break;
+        case "tool:exitSelectionMode":
+          s.selectionMode = false;
+          document.body.style.cursor = "";
+          if (s.highlightOverlay) s.highlightOverlay.style.display = "none";
+          if (s.tooltip) s.tooltip.style.display = "none";
+          s.hoveredElement = null;
+          break;
+        case "tool:previewInlineStyle": {
+          if (s.selectedElement && s.selectedElement instanceof HTMLElement) {
+            const prop = msg.property as string;
+            const value = msg.value as string;
+            if (!s.inlineStyleBackups.has(prop)) {
+              s.inlineStyleBackups.set(prop, s.selectedElement.style.getPropertyValue(prop));
+            }
+            s.selectedElement.style.setProperty(prop, value, "important");
+          }
+          break;
+        }
+        case "tool:revertInlineStyles": {
+          if (s.selectedElement && s.selectedElement instanceof HTMLElement) {
+            for (const [prop, original] of s.inlineStyleBackups) {
+              if (original) {
+                s.selectedElement.style.setProperty(prop, original);
+              } else {
+                s.selectedElement.style.removeProperty(prop);
+              }
+            }
+            s.inlineStyleBackups.clear();
+          }
+          break;
+        }
+        case "tool:previewTokenValue": {
+          const prop = msg.property as string;
+          const value = msg.value as string;
+          // Track current preview value
+          s.tokenPreviewValues.set(prop, value);
+          // Inject a <style> tag override.
+          // Tailwind v4 resolves @theme variables at build time and inlines
+          // them into utility classes, so setting CSS custom properties on
+          // :root has no effect. Instead we target utility classes directly.
+          if (!s.tokenPreviewStyle) {
+            s.tokenPreviewStyle = document.createElement("style");
+            s.tokenPreviewStyle.id = "codesurface-token-preview";
+            document.head.appendChild(s.tokenPreviewStyle);
+          }
+          const cssRules: string[] = [];
+          for (const [k, v] of s.tokenPreviewValues) {
+            // Derive Tailwind utility class from CSS variable name:
+            // --shadow-sm → .shadow-sm, --shadow → .shadow
+            if (k.startsWith("--shadow")) {
+              const cls = k.slice(2); // "--shadow-sm" → "shadow-sm"
+              cssRules.push(`.${cls}, [class*="${cls}"] { box-shadow: ${v} !important; }`);
+            } else {
+              // For other tokens (colors, spacing, etc.) override the custom property
+              cssRules.push(`*, *::before, *::after { ${k}: ${v} !important; }`);
+            }
+          }
+          s.tokenPreviewStyle.textContent = cssRules.join("\n");
+          break;
+        }
+        case "tool:revertTokenValues": {
+          if (s.tokenPreviewStyle) {
+            s.tokenPreviewStyle.remove();
+            s.tokenPreviewStyle = null;
+          }
+          s.tokenPreviewValues.clear();
+          s.tokenValueBackups.clear();
+          break;
+        }
+        case "tool:reselectElement":
+          reselectCurrentElement();
+          break;
+        case "tool:setTheme":
+          if (msg.theme === "dark") {
+            document.documentElement.classList.add("dark");
+          } else {
+            document.documentElement.classList.remove("dark");
+          }
+          break;
+      }
+    }
+
+    function notifyPathChanged() {
+      const fullPath = window.location.pathname + window.location.search + window.location.hash;
+      window.parent.postMessage({ type: "tool:pathChanged", path: fullPath }, "*");
+    }
+
+    // --- Init ---
+    document.addEventListener("mousemove", onMouseMove, true);
+    document.addEventListener("mouseleave", onMouseLeave);
+    document.addEventListener("click", onClick, true);
+    window.addEventListener("message", onMessage);
+    window.addEventListener("popstate", notifyPathChanged);
+
+    // Notify editor that we're ready
+    window.parent.postMessage({ type: "tool:injectedReady" }, "*");
+    notifyPathChanged();
+
+    // --- Cleanup ---
+    return () => {
+      document.removeEventListener("mousemove", onMouseMove, true);
+      document.removeEventListener("mouseleave", onMouseLeave);
+      document.removeEventListener("click", onClick, true);
+      window.removeEventListener("message", onMessage);
+      window.removeEventListener("popstate", notifyPathChanged);
+
+      if (s.overlayRafId) cancelAnimationFrame(s.overlayRafId);
+      s.tokenPreviewStyle?.remove();
+      s.highlightOverlay?.remove();
+      s.tooltip?.remove();
+      s.selectedOverlay?.remove();
+    };
+  }, []);
+
+  // This component renders nothing — overlays are created imperatively
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Next.js config wrapper that adds the designtools source annotation loader
+ * and auto-mounts the <CodeSurface /> selection component in development.
+ *
+ * Usage:
+ *   import { withDesigntools } from "@designtools/next-plugin";
+ *   export default withDesigntools({ ...yourConfig });
+ */
+
+import path from "path";
+
+export function withDesigntools<T extends Record<string, any>>(nextConfig: T = {} as T): T {
+  return {
+    ...nextConfig,
+    webpack(config: any, context: any) {
+      // Only add the loader in development
+      if (context.dev) {
+        config.module.rules.push({
+          test: /\.(tsx|jsx)$/,
+          exclude: /node_modules/,
+          use: [
+            {
+              loader: path.resolve(__dirname, "loader.js"),
+              options: {
+                cwd: context.dir,
+              },
+            },
+          ],
+        });
+
+        // Add a loader for root layout files that auto-mounts <CodeSurface />
+        config.module.rules.push({
+          test: /layout\.(tsx|jsx)$/,
+          include: [
+            path.resolve(context.dir, "app"),
+            path.resolve(context.dir, "src/app"),
+          ],
+          use: [
+            {
+              loader: path.resolve(__dirname, "codesurface-mount-loader.js"),
+            },
+          ],
+        });
+      }
+
+      // Call the user's webpack config if provided
+      if (typeof nextConfig.webpack === "function") {
+        return nextConfig.webpack(config, context);
+      }
+
+      return config;
+    },
+  };
+}

package/src/loader.ts

@@ -0,0 +1,125 @@
+/**
+ * Webpack loader that adds data-source="file:line:col" attributes to JSX elements.
+ * Uses Babel's parser for correct JSX identification (avoids matching TypeScript generics).
+ * SWC stays enabled as the primary compiler — Babel is only used here for the source annotation pass.
+ */
+
+import path from "path";
+
+interface LoaderContext {
+  resourcePath: string;
+  rootContext: string;
+  getOptions(): { cwd?: string };
+  callback(err: Error | null, content?: string, sourceMap?: any): void;
+  async(): (err: Error | null, content?: string, sourceMap?: any) => void;
+}
+
+export default function designtoolsLoader(this: LoaderContext, source: string): void {
+  const callback = this.async();
+  const opts = this.getOptions();
+  const cwd = opts.cwd || this.rootContext || process.cwd();
+  const relativePath = path.relative(cwd, this.resourcePath);
+
+  // Skip node_modules
+  if (relativePath.includes("node_modules")) {
+    callback(null, source);
+    return;
+  }
+
+  // Quick check: skip files with no JSX
+  if (!source.includes("<")) {
+    callback(null, source);
+    return;
+  }
+
+  try {
+    // @babel/core is available at runtime via Next.js — don't bundle it
+    const babel = require("@babel/core");
+
+    const isTsx = this.resourcePath.endsWith(".tsx");
+
+    const result = babel.transformSync(source, {
+      filename: this.resourcePath,
+      // No presets — we only want to parse and run our visitor, not compile
+      presets: [],
+      plugins: [
+        function designtoolsSourcePlugin() {
+          return {
+            visitor: {
+              JSXOpeningElement(nodePath: any) {
+                const t = babel.types;
+                const attrs = nodePath.node.attributes;
+                const name = nodePath.node.name;
+
+                // Skip fragments
+                if (t.isJSXIdentifier(name) && name.name === "Fragment") return;
+                if (t.isJSXMemberExpression(name) &&
+                    t.isJSXIdentifier(name.property) &&
+                    name.property.name === "Fragment") return;
+
+                const loc = nodePath.node.loc;
+                if (!loc) return;
+
+                const value = `${relativePath}:${loc.start.line}:${loc.start.column}`;
+
+                // Detect component elements (uppercase first letter or member expression like Foo.Bar)
+                const isComponent =
+                  (t.isJSXIdentifier(name) && name.name[0] === name.name[0].toUpperCase() && name.name[0] !== name.name[0].toLowerCase()) ||
+                  t.isJSXMemberExpression(name);
+
+                if (isComponent) {
+                  // Component elements get data-instance-source — this attribute
+                  // propagates through {...props} spread to the rendered DOM element,
+                  // carrying the exact page-level coordinates of each component usage.
+                  // The component's own data-source (on its root native element) won't
+                  // collide because it uses a different attribute name.
+                  const attrName = "data-instance-source";
+                  if (attrs.some((a: any) =>
+                    t.isJSXAttribute(a) &&
+                    t.isJSXIdentifier(a.name) &&
+                    a.name.name === attrName
+                  )) return;
+                  attrs.push(
+                    t.jsxAttribute(
+                      t.jsxIdentifier(attrName),
+                      t.stringLiteral(value)
+                    )
+                  );
+                } else {
+                  // Native elements get data-source as before
+                  if (attrs.some((a: any) =>
+                    t.isJSXAttribute(a) &&
+                    t.isJSXIdentifier(a.name) &&
+                    a.name.name === "data-source"
+                  )) return;
+                  attrs.push(
+                    t.jsxAttribute(
+                      t.jsxIdentifier("data-source"),
+                      t.stringLiteral(value)
+                    )
+                  );
+                }
+              },
+            },
+          };
+        },
+      ],
+      // Tell Babel's parser to handle JSX and TypeScript syntax
+      parserOpts: {
+        plugins: ["jsx", ...(isTsx ? ["typescript" as const] : [])],
+      },
+      // Preserve original formatting as much as possible
+      retainLines: true,
+      // Don't look for user's .babelrc or babel.config — isolation
+      configFile: false,
+      babelrc: false,
+    });
+
+    callback(null, result?.code || source);
+  } catch (err: any) {
+    // If Babel fails, pass through the original source
+    // This ensures the app still works even if our plugin has issues
+    console.warn(`[designtools] Source annotation skipped for ${relativePath}: ${err.message}`);
+    callback(null, source);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}