@designtools/next-plugin 0.1.9 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # @designtools/next-plugin
 
-Next.js config wrapper for [@designtools/codesurface](../codesurface). Adds source location annotations and mounts the selection overlay — development only.
+Next.js config wrapper for [@designtools/surface](../surface). Adds source location annotations and mounts the selection overlay — development only.
 
 ## Installation
 
@@ -40,9 +40,9 @@ Runs a Babel pass over every `.tsx` / `.jsx` file (excluding `node_modules`) tha
 
 SWC stays enabled as the primary compiler — Babel is only used for this annotation pass.
 
-### 2. CodeSurface mount loader
+### 2. Surface mount loader
 
-Transforms your root layout file (`app/layout.tsx` or `src/app/layout.tsx`) to auto-mount the `<CodeSurface />` selection overlay component. This component handles element selection, hover highlighting, inline style previews, and postMessage communication with the editor UI.
+Transforms your root layout file (`app/layout.tsx` or `src/app/layout.tsx`) to auto-mount the `<Surface />` selection overlay component. This component handles element selection, hover highlighting, inline style previews, and postMessage communication with the editor UI.
 
 Both loaders are skipped entirely in production builds.
 
@@ -51,7 +51,21 @@ Both loaders are skipped entirely in production builds.
 | Export | Description |
 |--------|-------------|
 | `@designtools/next-plugin` | `withDesigntools()` config wrapper |
-| `@designtools/next-plugin/codesurface` | `<CodeSurface />` React component (mounted automatically — you shouldn't need to import this directly) |
+| `@designtools/next-plugin/surface` | `<Surface />` React component (mounted automatically — you shouldn't need to import this directly) |
+
+## Supported styling systems
+
+All styling systems supported by Surface work with the Next.js plugin:
+
+| System | Status |
+|--------|--------|
+| Tailwind CSS v3 / v4 | Stable |
+| CSS Variables | Stable |
+| Plain CSS | Stable |
+| CSS Modules | Stable |
+| Sass / SCSS | Planned |
+
+See the [Surface README](../surface/README.md) for the full support matrix.
 
 ## License
 

package/dist/codesurface-mount-loader.js

@@ -35,7 +35,7 @@ function codesurfaceMountLoader(source) {
   }
   const importStatements = [
     `import { CodeSurface } from "@designtools/next-plugin/codesurface";`,
-    `import "./designtools-registry";`
+    `import { DesigntoolsRegistry } from "./designtools-registry";`
   ].join("\n") + "\n";
   let modified = source;
   const firstImportIndex = source.indexOf("import ");
@@ -46,7 +46,7 @@ function codesurfaceMountLoader(source) {
   }
   modified = modified.replace(
     /(\{children\})/,
-    `<CodeSurface />
+    `<CodeSurface /><DesigntoolsRegistry />
           $1`
   );
   callback(null, modified);

package/dist/codesurface-mount-loader.mjs

@@ -13,7 +13,7 @@ function codesurfaceMountLoader(source) {
   }
   const importStatements = [
     `import { CodeSurface } from "@designtools/next-plugin/codesurface";`,
-    `import "./designtools-registry";`
+    `import { DesigntoolsRegistry } from "./designtools-registry";`
   ].join("\n") + "\n";
   let modified = source;
   const firstImportIndex = source.indexOf("import ");
@@ -24,7 +24,7 @@ function codesurfaceMountLoader(source) {
   }
   modified = modified.replace(
     /(\{children\})/,
-    `<CodeSurface />
+    `<CodeSurface /><DesigntoolsRegistry />
           $1`
   );
   callback(null, modified);

package/dist/codesurface.js

@@ -312,20 +312,18 @@ function CodeSurface() {
         const children = [];
         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
+        };
       }
-      if (el?.hasAttribute("data-source") && !skipTags.has(tag)) {
+      if (currentTreeMode === "dom" && el?.hasAttribute("data-source") && !skipTags.has(tag)) {
         const children = [];
         if (fiber.child) walkFiber(fiber.child, children, scope);
         const text = el ? getDirectText(el) : "";
@@ -454,14 +452,16 @@ function CodeSurface() {
         }
       }
     }
-    function sendComponentTree() {
+    let currentTreeMode = "components";
+    function sendComponentTree(mode) {
+      if (mode) currentTreeMode = mode;
       const tree = buildComponentTree(document.body);
       window.parent.postMessage({ type: "tool:componentTree", tree }, "*");
     }
     let debounceTimer = null;
     function debouncedSendTree() {
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(sendComponentTree, 300);
+      debounceTimer = setTimeout(() => sendComponentTree(), 300);
     }
     const treeObserver = new MutationObserver(debouncedSendTree);
     treeObserver.observe(document.body, { childList: true, subtree: true });
@@ -716,6 +716,15 @@ function CodeSurface() {
       if (s.tooltip) s.tooltip.style.display = "none";
       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;
+      }
+    }
     function onMouseMove(e) {
       if (!s.selectionMode || !s.highlightOverlay || !s.tooltip) return;
       const el = document.elementFromPoint(e.clientX, e.clientY);
@@ -756,6 +765,9 @@ 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;
@@ -821,7 +833,7 @@ function CodeSurface() {
           }
           break;
         case "tool:requestComponentTree":
-          sendComponentTree();
+          sendComponentTree(msg.mode || "components");
           break;
         case "tool:highlightByTreeId": {
           const id = msg.id;

package/dist/codesurface.mjs

@@ -290,20 +290,18 @@ function CodeSurface() {
         const children = [];
         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
+        };
       }
-      if (el?.hasAttribute("data-source") && !skipTags.has(tag)) {
+      if (currentTreeMode === "dom" && el?.hasAttribute("data-source") && !skipTags.has(tag)) {
         const children = [];
         if (fiber.child) walkFiber(fiber.child, children, scope);
         const text = el ? getDirectText(el) : "";
@@ -432,14 +430,16 @@ function CodeSurface() {
         }
       }
     }
-    function sendComponentTree() {
+    let currentTreeMode = "components";
+    function sendComponentTree(mode) {
+      if (mode) currentTreeMode = mode;
       const tree = buildComponentTree(document.body);
       window.parent.postMessage({ type: "tool:componentTree", tree }, "*");
     }
     let debounceTimer = null;
     function debouncedSendTree() {
       if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(sendComponentTree, 300);
+      debounceTimer = setTimeout(() => sendComponentTree(), 300);
     }
     const treeObserver = new MutationObserver(debouncedSendTree);
     treeObserver.observe(document.body, { childList: true, subtree: true });
@@ -694,6 +694,15 @@ function CodeSurface() {
       if (s.tooltip) s.tooltip.style.display = "none";
       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;
+      }
+    }
     function onMouseMove(e) {
       if (!s.selectionMode || !s.highlightOverlay || !s.tooltip) return;
       const el = document.elementFromPoint(e.clientX, e.clientY);
@@ -734,6 +743,9 @@ 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;
@@ -799,7 +811,7 @@ function CodeSurface() {
           }
           break;
         case "tool:requestComponentTree":
-          sendComponentTree();
+          sendComponentTree(msg.mode || "components");
           break;
         case "tool:highlightByTreeId": {
           const id = msg.id;

package/dist/index.d.mts

@@ -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";

package/dist/index.d.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";

package/dist/index.js

@@ -50,11 +50,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;
+}
 `;
   import_fs.default.writeFileSync(import_path.default.join(appDir, REGISTRY_FILE), content, "utf-8");
   ensureGitignore(projectRoot);
@@ -117,7 +123,7 @@ function withDesigntools(nextConfig = {}) {
           ],
           use: [
             {
-              loader: import_path2.default.resolve(__dirname, "codesurface-mount-loader.js")
+              loader: import_path2.default.resolve(__dirname, "surface-mount-loader.js")
             }
           ]
         });
@@ -138,7 +144,7 @@ function withDesigntools(nextConfig = {}) {
       }
     };
     const mountLoader = {
-      loader: import_path2.default.resolve(__dirname, "codesurface-mount-loader.js")
+      loader: import_path2.default.resolve(__dirname, "surface-mount-loader.js")
     };
     const sourceRule = {
       loaders: [sourceLoader],

package/dist/index.mjs

@@ -18,11 +18,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");
   ensureGitignore(projectRoot);
@@ -85,7 +91,7 @@ function withDesigntools(nextConfig = {}) {
           ],
           use: [
             {
-              loader: path2.resolve(__dirname, "codesurface-mount-loader.js")
+              loader: path2.resolve(__dirname, "surface-mount-loader.js")
             }
           ]
         });
@@ -106,7 +112,7 @@ function withDesigntools(nextConfig = {}) {
       }
     };
     const mountLoader = {
-      loader: path2.resolve(__dirname, "codesurface-mount-loader.js")
+      loader: path2.resolve(__dirname, "surface-mount-loader.js")
     };
     const sourceRule = {
       loaders: [sourceLoader],

package/dist/surface-mount-loader.d.mts

@@ -0,0 +1,15 @@
+/**
+ * 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 <Surface /> alongside it.
+ */
+interface LoaderContext {
+    resourcePath: string;
+    callback(err: Error | null, content?: string): void;
+    async(): (err: Error | null, content?: string) => void;
+}
+declare function surfaceMountLoader(this: LoaderContext, source: string): void;
+
+export { surfaceMountLoader as default };

package/dist/surface-mount-loader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 <Surface /> alongside it.
+ */
+interface LoaderContext {
+    resourcePath: string;
+    callback(err: Error | null, content?: string): void;
+    async(): (err: Error | null, content?: string) => void;
+}
+declare function surfaceMountLoader(this: LoaderContext, source: string): void;
+
+export { surfaceMountLoader as default };

package/dist/surface-mount-loader.js

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/surface-mount-loader.ts
+var surface_mount_loader_exports = {};
+__export(surface_mount_loader_exports, {
+  default: () => surfaceMountLoader
+});
+module.exports = __toCommonJS(surface_mount_loader_exports);
+function surfaceMountLoader(source) {
+  const callback = this.async();
+  if (!source.includes("<html")) {
+    callback(null, source);
+    return;
+  }
+  if (source.includes("Surface")) {
+    callback(null, source);
+    return;
+  }
+  const importStatements = [
+    `import { Surface } from "@designtools/next-plugin/surface";`,
+    `import { DesigntoolsRegistry } from "./designtools-registry";`
+  ].join("\n") + "\n";
+  let modified = source;
+  const firstImportIndex = source.indexOf("import ");
+  if (firstImportIndex !== -1) {
+    modified = source.slice(0, firstImportIndex) + importStatements + source.slice(firstImportIndex);
+  } else {
+    modified = importStatements + source;
+  }
+  modified = modified.replace(
+    /(\{children\})/,
+    `<Surface /><DesigntoolsRegistry />
+          $1`
+  );
+  callback(null, modified);
+}

package/dist/surface-mount-loader.mjs

@@ -0,0 +1,34 @@
+import "./chunk-Y6FXYEAI.mjs";
+
+// src/surface-mount-loader.ts
+function surfaceMountLoader(source) {
+  const callback = this.async();
+  if (!source.includes("<html")) {
+    callback(null, source);
+    return;
+  }
+  if (source.includes("Surface")) {
+    callback(null, source);
+    return;
+  }
+  const importStatements = [
+    `import { Surface } from "@designtools/next-plugin/surface";`,
+    `import { DesigntoolsRegistry } from "./designtools-registry";`
+  ].join("\n") + "\n";
+  let modified = source;
+  const firstImportIndex = source.indexOf("import ");
+  if (firstImportIndex !== -1) {
+    modified = source.slice(0, firstImportIndex) + importStatements + source.slice(firstImportIndex);
+  } else {
+    modified = importStatements + source;
+  }
+  modified = modified.replace(
+    /(\{children\})/,
+    `<Surface /><DesigntoolsRegistry />
+          $1`
+  );
+  callback(null, modified);
+}
+export {
+  surfaceMountLoader as default
+};

package/dist/surface.d.mts

@@ -0,0 +1,5 @@
+import * as react from 'react';
+
+declare function Surface(): react.ReactPortal | null;
+
+export { Surface };

package/dist/surface.d.ts

@@ -0,0 +1,5 @@
+import * as react from 'react';
+
+declare function Surface(): react.ReactPortal | null;
+
+export { Surface };