@designtools/next-plugin 0.1.9 → 0.1.10

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@designtools/next-plugin",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "main": "dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andflett/designtools"
+  },
   "exports": {
     ".": {
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
     },
-    "./codesurface": {
-      "require": "./dist/codesurface.js",
-      "import": "./dist/codesurface.mjs"
+    "./surface": {
+      "require": "./dist/surface.js",
+      "import": "./dist/surface.mjs"
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/loader.ts src/codesurface.tsx src/codesurface-mount-loader.ts --format cjs,esm --dts --external @babel/core --external react --external react/jsx-runtime --external react-dom"
+    "build": "tsup src/index.ts src/loader.ts src/surface.tsx src/surface-mount-loader.ts --format cjs,esm --dts --external @babel/core --external react --external react/jsx-runtime --external react-dom"
   },
   "peerDependencies": {
     "next": ">=14.0.0",

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * Next.js config wrapper that adds the designtools source annotation loader
- * and auto-mounts the <CodeSurface /> selection component in development.
+ * and auto-mounts the <Surface /> selection component in development.
  *
  * Usage:
  *   import { withDesigntools } from "@designtools/next-plugin";
@@ -39,7 +39,7 @@ export function withDesigntools<T extends Record<string, any>>(nextConfig: T = {
           ],
         });
 
-        // Add a loader for root layout files that auto-mounts <CodeSurface />
+        // Add a loader for root layout files that auto-mounts <Surface />
         config.module.rules.push({
           test: /layout\.(tsx|jsx)$/,
           include: [
@@ -48,7 +48,7 @@ export function withDesigntools<T extends Record<string, any>>(nextConfig: T = {
           ],
           use: [
             {
-              loader: path.resolve(__dirname, "codesurface-mount-loader.js"),
+              loader: path.resolve(__dirname, "surface-mount-loader.js"),
             },
           ],
         });
@@ -79,7 +79,7 @@ export function withDesigntools<T extends Record<string, any>>(nextConfig: T = {
     };
 
     const mountLoader = {
-      loader: path.resolve(__dirname, "codesurface-mount-loader.js"),
+      loader: path.resolve(__dirname, "surface-mount-loader.js"),
     };
 
     // Source annotation loader for all .tsx/.jsx files (excluding node_modules)

package/src/preview-route.ts

@@ -2,7 +2,7 @@
  * Component registry generator for component isolation.
  *
  * Writes a static import map file into the target app's app directory.
- * The <CodeSurface /> component uses this registry to dynamically load
+ * The <Surface /> component uses this registry to dynamically load
  * components for the isolation overlay — no route change needed.
  */
 
@@ -29,11 +29,17 @@ const COMPONENT_REGISTRY: Record<string, () => Promise<any>> = {
 ${registryEntries}
 };
 
-// Self-register on window so CodeSurface can access it without
+// Self-register on window so Surface can access it without
 // passing functions through the RSC serialization boundary.
 if (typeof window !== "undefined") {
   (window as any).__DESIGNTOOLS_REGISTRY__ = COMPONENT_REGISTRY;
 }
+
+// Exported as a rendered component to prevent tree-shaking of the
+// side-effect registration above. The mount loader renders this in layout.
+export function DesigntoolsRegistry() {
+  return null;
+}
 `;
 
   fs.writeFileSync(path.join(appDir, REGISTRY_FILE), content, "utf-8");

package/src/{codesurface-mount-loader.ts → surface-mount-loader.ts}

@@ -1,9 +1,9 @@
 /**
- * Webpack loader that auto-mounts <CodeSurface /> in the root layout.
+ * Webpack loader that auto-mounts <Surface /> in the root layout.
  * Only runs in development. Injects the import and component into the JSX.
  *
  * Strategy: Simple string injection — find the {children} pattern in the layout
- * and add <CodeSurface /> alongside it.
+ * and add <Surface /> alongside it.
  */
 
 interface LoaderContext {
@@ -12,7 +12,7 @@ interface LoaderContext {
   async(): (err: Error | null, content?: string) => void;
 }
 
-export default function codesurfaceMountLoader(this: LoaderContext, source: string): void {
+export default function surfaceMountLoader(this: LoaderContext, source: string): void {
   const callback = this.async();
 
   // Only inject into root layout (not nested layouts)
@@ -22,17 +22,17 @@ export default function codesurfaceMountLoader(this: LoaderContext, source: stri
     return;
   }
 
-  // Skip if already has CodeSurface import
-  if (source.includes("CodeSurface")) {
+  // Skip if already has Surface import
+  if (source.includes("Surface")) {
     callback(null, source);
     return;
   }
 
   // Add imports at the top (after "use client" or first import)
-  // The registry import is a side-effect — it self-registers on window.
+  // The registry is rendered as a component to prevent tree-shaking.
   const importStatements = [
-    `import { CodeSurface } from "@designtools/next-plugin/codesurface";`,
-    `import "./designtools-registry";`,
+    `import { Surface } from "@designtools/next-plugin/surface";`,
+    `import { DesigntoolsRegistry } from "./designtools-registry";`,
   ].join("\n") + "\n";
 
   let modified = source;
@@ -45,10 +45,10 @@ export default function codesurfaceMountLoader(this: LoaderContext, source: stri
     modified = importStatements + source;
   }
 
-  // Add <CodeSurface /> just before {children}
+  // Add <Surface /> and <DesigntoolsRegistry /> just before {children}
   modified = modified.replace(
     /(\{children\})/,
-    `<CodeSurface />\n          $1`
+    `<Surface /><DesigntoolsRegistry />\n          $1`
   );
 
   callback(null, modified);

package/src/{codesurface.tsx → surface.tsx}

@@ -1,7 +1,7 @@
 "use client";
 
 /**
- * <CodeSurface /> — Selection overlay component for the target app.
+ * <Surface /> — Selection overlay component for the target app.
  * Mounted automatically by withDesigntools() in development.
  * Communicates with the editor UI via postMessage.
  *
@@ -21,7 +21,7 @@ interface PreviewCombination {
   props: Record<string, string>;
 }
 
-export function CodeSurface() {
+export function Surface() {
   const stateRef = useRef({
     selectionMode: false,
     hoveredElement: null as Element | null,
@@ -157,7 +157,7 @@ export function CodeSurface() {
     // --- Component tree extraction (React Fiber) ---
 
     // IDs of overlay elements to skip during tree building
-    const overlayIds = new Set(["tool-highlight", "tool-tooltip", "tool-selected", "codesurface-token-preview"]);
+    const overlayIds = new Set(["tool-highlight", "tool-tooltip", "tool-selected", "surface-token-preview"]);
 
     // Semantic HTML elements shown as structural landmarks
     const semanticTags = new Set(["header", "main", "nav", "section", "article", "footer", "aside"]);
@@ -364,29 +364,30 @@ export function CodeSurface() {
         };
       }
 
-      // Show semantic HTML landmarks
+      // Show semantic HTML landmarks — always show these as structural markers
       if (semanticTags.has(tag)) {
         const children: TreeNode[] = [];
         if (fiber.child) walkFiber(fiber.child, children, scope);
         const text = el ? getDirectText(el) : "";
-        if (children.length > 0 || text) {
-          return {
-            id: el ? getDomPath(el) : "",
-            name: `<${tag}>`,
-            type: "element",
-            dataSlot: null,
-            source: el?.getAttribute("data-source") || null,
-            scope,
-            textContent: text,
-            children,
-          };
-        }
+        return {
+          id: el ? getDomPath(el) : "",
+          name: `<${tag}>`,
+          type: "element",
+          dataSlot: null,
+          source: el?.getAttribute("data-source") || null,
+          scope,
+          textContent: text,
+          children,
+        };
       }
 
       // Show authored elements — data-source is added by our Babel transform
       // to every JSX element, so its presence proves this was deliberately
       // written in user code. Skip document/void tags that aren't meaningful.
-      if (el?.hasAttribute("data-source") && !skipTags.has(tag)) {
+      // In "components" mode, skip generic elements to reduce noise (only
+      // data-slot components and semantic landmarks show). In "dom" mode,
+      // show all authored elements.
+      if (currentTreeMode === "dom" && el?.hasAttribute("data-source") && !skipTags.has(tag)) {
         const children: TreeNode[] = [];
         if (fiber.child) walkFiber(fiber.child, children, scope);
         const text = el ? getDirectText(el) : "";
@@ -418,8 +419,8 @@ export function CodeSurface() {
       // Skip framework internals
       if (isFrameworkComponent(name)) return null;
 
-      // Skip the CodeSurface component itself
-      if (name === "CodeSurface") return null;
+      // Skip the Surface component itself
+      if (name === "Surface") return null;
 
       // Find this component's own root host element — only walk down through
       // non-host fibers (other components, fragments, etc.) to find the first
@@ -580,7 +581,11 @@ export function CodeSurface() {
       }
     }
 
-    function sendComponentTree() {
+    // Current tree mode — stored so MutationObserver re-sends use the same mode
+    let currentTreeMode: "components" | "dom" = "components";
+
+    function sendComponentTree(mode?: "components" | "dom") {
+      if (mode) currentTreeMode = mode;
       const tree = buildComponentTree(document.body);
       window.parent.postMessage({ type: "tool:componentTree", tree }, "*");
     }
@@ -589,7 +594,7 @@ export function CodeSurface() {
     let debounceTimer: ReturnType<typeof setTimeout> | null = null;
     function debouncedSendTree() {
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(sendComponentTree, 300);
+      debounceTimer = setTimeout(() => sendComponentTree(), 300);
     }
 
     // MutationObserver to send updated tree on DOM changes (HMR, dynamic content)
@@ -711,10 +716,11 @@ export function CodeSurface() {
       let instanceSourceLine: number | null = null;
       let instanceSourceCol: number | null = null;
       let componentName: string | null = null;
+      let packageName: string | null = null;
 
       const dataSlot = el.getAttribute("data-slot");
       const instanceSource = el.getAttribute("data-instance-source");
-      if (instanceSource && dataSlot) {
+      if (instanceSource) {
         const lc = instanceSource.lastIndexOf(":");
         const slc = instanceSource.lastIndexOf(":", lc - 1);
         if (slc > 0) {
@@ -723,19 +729,44 @@ export function CodeSurface() {
           instanceSourceCol = parseInt(instanceSource.slice(lc + 1), 10);
         }
 
-        // Derive component name from data-slot (e.g. "card-title" -> "CardTitle")
-        componentName = dataSlot
-          .split("-")
-          .map((s: string) => s.charAt(0).toUpperCase() + s.slice(1))
-          .join("");
+        if (dataSlot) {
+          // Derive component name from data-slot (e.g. "card-title" -> "CardTitle")
+          componentName = dataSlot
+            .split("-")
+            .map((s: string) => s.charAt(0).toUpperCase() + s.slice(1))
+            .join("");
+        }
       }
 
-      // Extract runtime props from React fiber for component instances
+      // Extract runtime props and derive componentName/packageName from React fiber
+      const compFiber = (dataSlot || instanceSource) ? findComponentFiberAbove(el) : null;
+
       let fiberProps: Record<string, string | number | boolean> | null = null;
-      if (dataSlot) {
-        const compFiber = findComponentFiberAbove(el);
-        if (compFiber) {
-          fiberProps = extractFiberProps(compFiber);
+      if (compFiber) {
+        fiberProps = extractFiberProps(compFiber);
+
+        // Derive componentName from fiber when data-slot is not present
+        if (!componentName && instanceSource) {
+          const name = compFiber.type?.displayName || compFiber.type?.name;
+          if (name) componentName = name;
+        }
+
+        // Extract packageName from fiber._debugSource for npm components
+        const debugFile = compFiber._debugSource?.fileName;
+        if (debugFile) {
+          packageName = extractPackageName(debugFile);
+        }
+      }
+
+      // Also check data-source for packageName if no fiber source
+      if (!packageName && !sourceFile) {
+        // No project source — try walking up fibers to find node_modules origin
+        const anyFiber = findComponentFiberAbove(el);
+        if (anyFiber) {
+          const debugFile = anyFiber._debugSource?.fileName;
+          if (debugFile) {
+            packageName = extractPackageName(debugFile);
+          }
         }
       }
 
@@ -755,10 +786,22 @@ export function CodeSurface() {
         instanceSourceLine,
         instanceSourceCol,
         componentName,
+        packageName,
         fiberProps,
       };
     }
 
+    function extractPackageName(filePath: string): string | null {
+      const nmIdx = filePath.lastIndexOf("node_modules/");
+      if (nmIdx === -1) return null;
+      const rest = filePath.slice(nmIdx + "node_modules/".length);
+      if (rest.startsWith("@")) {
+        const parts = rest.split("/");
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+      }
+      return rest.split("/")[0] || null;
+    }
+
     function selectElement(el: Element) {
       s.selectedElement = el;
       s.selectedDomPath = getDomPath(el);
@@ -832,6 +875,16 @@ export function CodeSurface() {
       s.hoveredElement = null;
     }
 
+    function clearSelection() {
+      s.selectedElement = null;
+      s.selectedDomPath = null;
+      if (s.selectedOverlay) s.selectedOverlay.style.display = "none";
+      if (s.overlayRafId) {
+        cancelAnimationFrame(s.overlayRafId);
+        s.overlayRafId = null;
+      }
+    }
+
     // --- Event handlers ---
     function onMouseMove(e: MouseEvent) {
       if (!s.selectionMode || !s.highlightOverlay || !s.tooltip) return;
@@ -877,6 +930,9 @@ export function CodeSurface() {
         case "tool:exitSelectionMode":
           exitSelectionMode();
           break;
+        case "tool:clearSelection":
+          clearSelection();
+          break;
         case "tool:previewInlineStyle": {
           if (s.selectedElement && s.selectedElement instanceof HTMLElement) {
             const prop = msg.property as string;
@@ -907,7 +963,7 @@ export function CodeSurface() {
           s.tokenPreviewValues.set(prop, value);
           if (!s.tokenPreviewStyle) {
             s.tokenPreviewStyle = document.createElement("style");
-            s.tokenPreviewStyle.id = "codesurface-token-preview";
+            s.tokenPreviewStyle.id = "surface-token-preview";
             document.head.appendChild(s.tokenPreviewStyle);
           }
           const cssRules: string[] = [];
@@ -942,7 +998,7 @@ export function CodeSurface() {
           }
           break;
         case "tool:requestComponentTree":
-          sendComponentTree();
+          sendComponentTree((msg as any).mode || "components");
           break;
         case "tool:highlightByTreeId": {
           const id = msg.id as string;
@@ -973,6 +1029,18 @@ export function CodeSurface() {
           }
           break;
         }
+        case "tool:selectParentInstance": {
+          if (!s.selectedElement) break;
+          let el: Element | null = s.selectedElement.parentElement;
+          while (el && el !== document.body) {
+            if (el.getAttribute("data-instance-source")) {
+              selectElement(el);
+              break;
+            }
+            el = el.parentElement;
+          }
+          break;
+        }
         case "tool:renderPreview": {
           const { componentPath, exportName, combinations: combos, defaultChildren: children } = msg;
           const currentRegistry = (window as any).__DESIGNTOOLS_REGISTRY__ as Record<string, () => Promise<any>> | undefined;