@promakeai/inspector 0.0.3 → 0.1.0

package/README.md

@@ -11,6 +11,8 @@ Visual element inspector for React apps in iframe with AI prompt support. Perfec
 - 🎯 **Element Selection** - Click to select any element on the page
 - 🔍 **React Component Detection** - Automatically detects React components via Fiber
 - 📝 **Dynamic Content Input** - Show/hide text editing on-demand with `showContentInput()`
+- 🖼️ **Image Upload Support** - Custom drag & drop image uploader with preview
+- ⚡ **Immediate DOM Updates** - Optional instant feedback while backend processes
 - 🤖 **AI Prompt Support** - Always-visible prompt input for AI modifications
 - 🎨 **Visual Feedback** - Highlight selected elements with overlay
 - 🔒 **Pause Mode** - Lock selection and disable scroll while editing
@@ -20,6 +22,8 @@ Visual element inspector for React apps in iframe with AI prompt support. Perfec
 - 🌍 **Customizable Labels** - Multi-language support
 - 🚫 **Ignore Elements** - Mark elements as non-inspectable with `data-inspector-ignore`
 - 🔍 **Text Node Detection** - Automatically detect if selected element is a text node
+- 🖼️ **Image Node Detection** - Automatically detect if selected element is an image
+- 🏷️ **Promake Badge** - Optional "Built by Promake" badge with smooth animations
 - 📦 **TypeScript** - Full type safety
 
 ## Installation
@@ -55,64 +59,92 @@ import { useInspector } from "@promakeai/inspector/hook";
 function App() {
   const iframeRef = useRef<HTMLIFrameElement>(null);
 
-  const { isInspecting, toggleInspector, showContentInput } = useInspector(
-    iframeRef,
-    {
-      onElementSelected: (data) => {
-        console.log("Element selected:", data);
-        console.log("Is text node:", data.isTextNode);
-
-        // Access component info
-        console.log(data.component?.fileName);
-        console.log(data.component?.lineNumber);
-
-        // Show content input if it's a text node
-        if (data.isTextNode) {
-          showContentInput(true);
-        }
+  const { isInspecting, toggleInspector, showContentInput, showImageInput } =
+    useInspector(
+      iframeRef,
+      {
+        onElementSelected: (data) => {
+          console.log("Element selected:", data);
+          console.log("Is text node:", data.isTextNode);
+          console.log("Is image node:", data.isImageNode);
+
+          // Access component info
+          console.log(data.component?.fileName);
+          console.log(data.component?.lineNumber);
+
+          // Show content input if it's a text node
+          if (data.isTextNode) {
+            showContentInput(true);
+          }
+
+          // Show image input if it's an image node
+          if (data.isImageNode) {
+            showImageInput(true);
+          }
+        },
+        onPromptSubmitted: (data) => {
+          console.log("AI Prompt:", data.prompt);
+          // Send to your AI service
+          fetch("/api/ai-edit", {
+            method: "POST",
+            body: JSON.stringify({
+              prompt: data.prompt,
+              element: data.element,
+            }),
+          });
+        },
+        onTextUpdated: (data) => {
+          console.log("Text updated:", data.text);
+          // Save to backend
+        },
+        onImageUpdated: (data) => {
+          console.log("Image updated:", data.imageFile.name);
+          console.log("Image data (base64):", data.imageData);
+          // Upload to server
+          fetch("/api/upload-image", {
+            method: "POST",
+            body: JSON.stringify(data),
+          });
+        },
+        onInspectorClosed: () => {
+          console.log("Inspector closed");
+          // Update UI state, re-enable elements, etc.
+        },
+        onUrlChange: (data) => {
+          console.log("URL changed:", data.pathname);
+        },
+        onError: (data) => {
+          console.error("Error in template:", data);
+          // Send to error tracking service (Sentry, etc.)
+          // Sentry.captureException(new Error(data.message));
+        },
       },
-      onPromptSubmitted: (data) => {
-        console.log("AI Prompt:", data.prompt);
-        // Send to your AI service
-        fetch("/api/ai-edit", {
-          method: "POST",
-          body: JSON.stringify({
-            prompt: data.prompt,
-            element: data.element,
-          }),
-        });
+      {
+        // Optional: Custom labels
+        editText: "Edit Text",
+        textPlaceholder: "Enter text...",
+        updateText: "Update",
+        promptPlaceholder: "Ask AI for changes...",
+        editImage: "Change Image",
+        imageUploadTitle: "Select Image",
+        imageUploadHint: "Click or drag",
+        updateImage: "Update Image",
+        badgeText: "Built with Promake",
       },
-      onTextUpdated: (data) => {
-        console.log("Text updated:", data.text);
-        // Save to backend
-      },
-      onUrlChange: (data) => {
-        console.log("URL changed:", data.pathname);
-      },
-      onError: (data) => {
-        console.error("Error in template:", data);
-        // Send to error tracking service (Sentry, etc.)
-        // Sentry.captureException(new Error(data.message));
-      },
-    },
-    {
-      // Optional: Custom labels
-      editText: "Edit Text",
-      textPlaceholder: "Enter text...",
-      updateText: "Update",
-      promptPlaceholder: "Ask AI for changes...",
-    },
-    {
-      // Optional: Custom theme colors
-      backgroundColor: "#ffffff",
-      textColor: "#111827",
-      buttonColor: "#4417db",
-      buttonTextColor: "#ffffff",
-      inputBackgroundColor: "#f9fafb",
-      inputTextColor: "#111827",
-      inputBorderColor: "#d1d5db",
-    }
-  );
+      {
+        // Optional: Custom theme colors
+        backgroundColor: "#ffffff",
+        textColor: "#111827",
+        buttonColor: "#4417db",
+        buttonTextColor: "#ffffff",
+        inputBackgroundColor: "#f9fafb",
+        inputTextColor: "#111827",
+        inputBorderColor: "#d1d5db",
+        badgeGradientStart: "#411E93",
+        badgeGradientEnd: "#E87C85",
+        badgeTextColor: "#ffffff",
+      }
+    );
 
   return (
     <div>
@@ -141,9 +173,11 @@ function App() {
 
 - **iframeRef**: `RefObject<HTMLIFrameElement>` - Reference to the iframe element
 - **callbacks**: `InspectorCallbacks` (optional)
-  - `onElementSelected`: Called when an element is selected (receives `isTextNode` property)
+  - `onElementSelected`: Called when an element is selected (receives `isTextNode` and `isImageNode` properties)
   - `onPromptSubmitted`: Called when AI prompt is submitted
   - `onTextUpdated`: Called when text content is updated
+  - `onImageUpdated`: Called when image is uploaded
+  - `onInspectorClosed`: Called when inspector mode is closed (after submitting prompt/text/image)
   - `onUrlChange`: Called when URL changes in iframe
   - `onError`: Called when an error occurs in iframe
 - **labels**: `InspectorLabels` (optional)
@@ -151,6 +185,11 @@ function App() {
   - `textPlaceholder`: Placeholder for text input
   - `updateText`: Label for update button
   - `promptPlaceholder`: Placeholder for prompt input
+  - `editImage`: Label for image edit section
+  - `imageUploadTitle`: Upload box title (e.g., "Select Image")
+  - `imageUploadHint`: Upload box hint (e.g., "Click or drag")
+  - `updateImage`: Label for image update button
+  - `badgeText`: Badge text (default: "Built with Promake")
 - **theme**: `InspectorTheme` (optional)
   - `backgroundColor`: Box background color (default: `#ffffff`)
   - `textColor`: Text color (default: `#111827`)
@@ -159,6 +198,9 @@ function App() {
   - `inputBackgroundColor`: Input background color (default: `#f9fafb`)
   - `inputTextColor`: Input text color (default: `#111827`)
   - `inputBorderColor`: Input border color (default: `#d1d5db`)
+  - `badgeGradientStart`: Badge gradient start color (default: `#411E93`)
+  - `badgeGradientEnd`: Badge gradient end color (default: `#E87C85`)
+  - `badgeTextColor`: Badge text color (default: `#ffffff`)
 
 #### Returns
 
@@ -166,7 +208,9 @@ function App() {
 - **toggleInspector**: `(active?: boolean) => void` - Toggle inspection mode
 - **startInspecting**: `() => void` - Start inspecting
 - **stopInspecting**: `() => void` - Stop inspecting
-- **showContentInput**: `(show: boolean) => void` - Show or hide content input dynamically
+- **showContentInput**: `(show: boolean, updateImmediately?: boolean) => void` - Show or hide text content input dynamically. If `updateImmediately` is true, DOM is updated immediately on submit (useful for slow backend responses)
+- **showImageInput**: `(show: boolean, updateImmediately?: boolean) => void` - Show or hide image input dynamically. If `updateImmediately` is true, DOM is updated immediately on submit (useful for slow backend responses)
+- **setBadgeVisible**: `(visible: boolean) => void` - Show or hide "Built by Promake" badge in bottom-right corner
 
 ## Types
 
@@ -179,7 +223,10 @@ interface SelectedElementData {
   id: string;
   component: ComponentInfo | null;
   position: ElementPosition;
-  isTextNode?: boolean; // Whether the element is a text-only node
+  isTextNode?: boolean; // Whether the element is a text node
+  textContent?: string; // Text content of the element (if text node)
+  isImageNode?: boolean; // Whether the element is an image node
+  imageUrl?: string; // Image URL (if image node)
 }
 ```
 
@@ -213,6 +260,21 @@ interface TextUpdatedData {
 }
 ```
 
+### `ImageUpdatedData`
+
+```typescript
+interface ImageUpdatedData {
+  imageData: string; // Base64 encoded image data
+  imageFile: {
+    name: string;
+    size: number;
+    type: string;
+  };
+  originalImageUrl: string;
+  element: SelectedElementData;
+}
+```
+
 ### `ErrorData`
 
 ```typescript
@@ -227,6 +289,22 @@ interface ErrorData {
 }
 ```
 
+### `InspectorLabels`
+
+```typescript
+interface InspectorLabels {
+  editText?: string; // Label for text edit section
+  textPlaceholder?: string; // Placeholder for text input
+  updateText?: string; // Label for text update button
+  promptPlaceholder?: string; // Placeholder for prompt input
+  editImage?: string; // Label for image edit section
+  imageUploadTitle?: string; // Upload box title (e.g., "Select Image")
+  imageUploadHint?: string; // Upload box hint (e.g., "Click or drag")
+  updateImage?: string; // Label for image update button
+  badgeText?: string; // Badge text (default: "Built with Promake")
+}
+```
+
 ### `InspectorTheme`
 
 ```typescript
@@ -238,6 +316,9 @@ interface InspectorTheme {
   inputBackgroundColor?: string; // Input background color
   inputTextColor?: string; // Input text color
   inputBorderColor?: string; // Input border color
+  badgeGradientStart?: string; // Badge gradient start color
+  badgeGradientEnd?: string; // Badge gradient end color
+  badgeTextColor?: string; // Badge text color
 }
 ```
 
@@ -252,29 +333,167 @@ Click any element to select it. The inspector will:
 - Pause scrolling
 - Extract React component information
 - Detect if element is a text-only node (`isTextNode`)
+- Detect if element is an image node (`isImageNode`)
 
 ### Dynamic Content Input
 
-The inspector now uses a two-stage approach:
+The inspector now uses a three-stage approach:
 
 1. **Prompt Input (Always Visible)**: Every element shows a prompt input for AI instructions
-2. **Content Input (On-Demand)**: Text editing appears only when you call `showContentInput(true)`
+2. **Text Content Input (On-Demand)**: Text editing appears only when you call `showContentInput(true)`
+3. **Image Upload (On-Demand)**: Image upload appears only when you call `showImageInput(true)`
 
 This allows you to:
 
 - Run AI computations after selection
-- Decide programmatically when to show text editing
+- Decide programmatically when to show text editing or image upload
 - Keep the UI clean and focused
 
 ```typescript
 onElementSelected: (data) => {
   if (data.isTextNode) {
     // Show content input above prompt input
-    showContentInput(true);
+    // Pass true as second parameter for immediate DOM update
+    showContentInput(true, true);
+  }
+
+  if (data.isImageNode) {
+    // Show image upload for images
+    // Pass true as second parameter for immediate DOM update
+    showImageInput(true, true);
   }
 };
 ```
 
+### Image Upload
+
+For image elements:
+
+- **Custom Upload Box**: Dashed border box with drag & drop support
+- **Click to Upload**: Click the box to select image from file explorer
+- **Drag & Drop**: Drag image files directly onto the upload box
+- **Preview**: Selected image appears in the same box (max 100px height)
+- **Base64 Encoding**: Image is automatically converted to base64
+- **File Metadata**: File name, size, and type are included
+
+The image data is sent to parent app with `onImageUpdated` callback for upload to your server.
+
+### Immediate DOM Updates
+
+For production environments where backend processing takes time, you can enable immediate DOM updates:
+
+```typescript
+// Text updates - DOM is updated immediately, no wait for backend
+showContentInput(true, true); // updateImmediately: true
+
+// Image updates - Image appears immediately, no wait for backend
+showImageInput(true, true); // updateImmediately: true
+```
+
+**How it works:**
+
+1. **Text Updates**: When user submits new text, the DOM text content is updated immediately
+2. **Image Updates**: When user selects an image, the `<img>` src (or background-image) is updated immediately with base64 data
+3. **Backend Sync**: The `onTextUpdated` or `onImageUpdated` callback is still fired for backend sync
+4. **User Experience**: User sees instant feedback, while your backend processes in the background
+
+This is perfect for:
+
+- Slow API responses
+- AI processing that takes seconds
+- Upload-heavy operations
+- Better perceived performance
+
+### Promake Badge
+
+Show a beautiful "Built with Promake" badge in the bottom-right corner:
+
+```typescript
+// Show badge with default text ("Built with Promake")
+setBadgeVisible(true);
+
+// Hide badge
+setBadgeVisible(false);
+
+// Customize badge text via labels
+const { setBadgeVisible } = useInspector(iframeRef, callbacks, {
+  badgeText: "Made with ❤️ by MyCompany",
+});
+
+// Customize badge colors via theme
+const { setBadgeVisible } = useInspector(
+  iframeRef,
+  callbacks,
+  undefined, // no custom labels
+  {
+    badgeGradientStart: "#10b981", // Green
+    badgeGradientEnd: "#3b82f6", // Blue
+    badgeTextColor: "#ffffff", // White text
+  }
+);
+
+// Dark badge with light text
+const { setBadgeVisible } = useInspector(iframeRef, callbacks, undefined, {
+  badgeGradientStart: "#1e293b", // Dark slate
+  badgeGradientEnd: "#334155", // Slate
+  badgeTextColor: "#f8fafc", // Light text
+});
+```
+
+**Features:**
+
+- 🎨 Beautiful gradient design (purple to violet by default)
+- ⚡ Smooth fade-in/fade-out animations
+- 🖱️ Hover effects with elevation
+- 🔗 Clickable - opens promake.ai in new tab
+- 📍 Fixed position in bottom-right
+- 🚫 Ignored by inspector (has `data-inspector-ignore`)
+- 📝 Customizable text via labels
+- 🎨 Customizable gradient colors via theme
+- 🔤 Customizable text color via theme
+- ❌ Close button appears on hover - users can dismiss the badge
+
+**Default**: Badge is hidden by default. Enable it when needed using `setBadgeVisible(true)`. Default text is "Built with Promake". Default gradient colors are deep purple (#411E93) to coral pink (#E87C85). Default text color is white (#ffffff).
+
+**Auto-Show**: Badge automatically appears when the app is running in `preview.promake.ai` environment **without** a parent iframe. This ensures the badge is visible in preview deployments where parent control is not available.
+
+**Close Button**: When users hover over the badge, a small close button (×) appears in the top-right corner. Clicking it hides the badge with a smooth animation.
+
+**Color Examples:**
+
+**Gradient Backgrounds:**
+
+- **Deep Purple to Coral Pink** (default): `#411E93` → `#E87C85` (white text)
+- **Blue to Cyan**: `#3b82f6` → `#06b6d4` (white text)
+- **Green to Emerald**: `#10b981` → `#059669` (white text)
+- **Pink to Rose**: `#ec4899` → `#f43f5e` (white text)
+- **Orange to Red**: `#f97316` → `#ef4444` (white text)
+- **Dark Slate**: `#1e293b` → `#334155` (light text `#f8fafc`)
+
+**Text Colors:**
+
+- **White** (default): `#ffffff`
+- **Light**: `#f8fafc`, `#f1f5f9`
+- **Dark**: `#111827`, `#1e293b`
+- **Brand Colors**: Match your brand palette
+
+**Auto-Show Behavior:**
+
+The badge automatically appears in these conditions:
+
+1. The app is **not** inside an iframe (`window.parent === window`)
+2. The URL contains `preview.promake.ai`
+
+This ensures the badge is visible in Promake preview deployments where parent window control is unavailable. Users can still close it using the close button on hover.
+
+**Use Cases:**
+
+- Show attribution to Promake
+- Free tier watermark for preview deployments
+- Branding for templates built with Promake
+- Custom branding with your own text and colors
+- Automatic display in preview environments
+
 ### AI Prompts
 
 For any element:
@@ -458,31 +677,17 @@ const { toggleInspector } = useInspector(iframeRef, {
 
 ## CI/CD
 
-This project includes GitHub Actions workflows:
+This project includes GitHub Actions workflow:
 
 ### Build Workflow (`.github/workflows/build.yml`)
 
 Automatically runs on every push and pull request:
 
-- ✅ Builds the package on Node.js 18.x and 20.x
-- ✅ Validates TypeScript compilation
+- ✅ Uses Bun for fast installation and build
+- ✅ Runs `bun install` and `bun run build`
 - ✅ Checks for build artifacts
 - ✅ Uploads build artifacts for review
 
-### Publish Workflow (`.github/workflows/publish.yml`)
-
-Automatically publishes to NPM when a release is created:
-
-- ✅ Builds the package
-- ✅ Publishes to NPM with `--access public`
-- ✅ Manual trigger support via workflow_dispatch
-
-**Setup for NPM publishing:**
-
-1. Create an NPM access token at [npmjs.com](https://www.npmjs.com/settings/YOUR_USERNAME/tokens)
-2. Add the token as `NPM_TOKEN` secret in your GitHub repository settings
-3. Create a release on GitHub to trigger automatic publishing
-
 ## License
 
 MIT

package/dist/hook.d.ts

@@ -12,16 +12,22 @@
  * function App() {
  *   const iframeRef = useRef<HTMLIFrameElement>(null);
  *
- *   const { isInspecting, toggleInspector, showContentInput } = useInspector(
+ *   const { isInspecting, toggleInspector, showContentInput, showImageInput } = useInspector(
  *     iframeRef,
  *     {
  *       onElementSelected: (data) => {
  *         console.log('Element selected:', data);
  *         console.log('Is text node:', data.isTextNode);
+ *         console.log('Is image node:', data.isImageNode);
  *
  *         // Dynamically show content input for text nodes
  *         if (data.isTextNode) {
- *           showContentInput(true);
+ *           showContentInput(true, true); // updateImmediately: true for instant feedback
+ *         }
+ *
+ *         // Dynamically show image input for image nodes
+ *         if (data.isImageNode) {
+ *           showImageInput(true, true); // updateImmediately: true for instant feedback
  *         }
  *       },
  *       onPromptSubmitted: (data) => {
@@ -35,6 +41,19 @@
  *       onTextUpdated: (data) => {
  *         console.log('Text updated:', data.text);
  *       },
+ *       onImageUpdated: (data) => {
+ *         console.log('Image updated:', data.imageFile.name);
+ *         console.log('Image data (base64):', data.imageData);
+ *         // Upload to server
+ *         fetch('/api/upload-image', {
+ *           method: 'POST',
+ *           body: JSON.stringify(data)
+ *         });
+ *       },
+ *       onInspectorClosed: () => {
+ *         console.log('Inspector closed');
+ *         // Update UI state, re-enable elements, etc.
+ *       },
  *       onError: (data) => {
  *         console.error('Error:', data);
  *         // Send to error tracking service
@@ -45,7 +64,12 @@
  *       editText: 'Edit Text',
  *       textPlaceholder: 'Enter text...',
  *       updateText: 'Update',
- *       promptPlaceholder: 'Ask AI for changes...'
+ *       promptPlaceholder: 'Ask AI for changes...',
+ *       editImage: 'Change Image',
+ *       imageUploadTitle: 'Select Image',
+ *       imageUploadHint: 'Click or drag',
+ *       updateImage: 'Update Image',
+ *       badgeText: 'Built with Promake'
  *     },
  *     {
  *       // Optional: Custom theme colors (all optional)
@@ -55,7 +79,10 @@
  *       buttonTextColor: '#ffffff',
  *       inputBackgroundColor: '#f9fafb',
  *       inputTextColor: '#111827',
- *       inputBorderColor: '#d1d5db'
+ *       inputBorderColor: '#d1d5db',
+ *       badgeGradientStart: '#411E93',
+ *       badgeGradientEnd: '#E87C85',
+ *       badgeTextColor: '#ffffff'
  *     }
  *   );
  *
@@ -66,7 +93,13 @@
  *           Toggle Inspector
  *         </button>
  *         <button onClick={() => showContentInput(true)}>
- *           Show Content Input
+ *           Show Text Input
+ *         </button>
+ *         <button onClick={() => showImageInput(true)}>
+ *           Show Image Input
+ *         </button>
+ *         <button onClick={() => setBadgeVisible(true)}>
+ *           Show Promake Badge
  *         </button>
  *       </div>
  *       <iframe ref={iframeRef} src="http://localhost:5173" />

package/dist/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAEH,OAAO,EAAoC,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,EAMnB,MAAM,SAAS,CAAC;AAoCjB,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,CAAC,iBAAiB,CAAC,EACvC,SAAS,CAAC,EAAE,kBAAkB,EAC9B,MAAM,CAAC,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,cAAc,GACrB,kBAAkB,CAyIpB;AAGD,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAEH,OAAO,EAAoC,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,EAOnB,MAAM,SAAS,CAAC;AAsDjB,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,CAAC,iBAAiB,CAAC,EACvC,SAAS,CAAC,EAAE,kBAAkB,EAC9B,MAAM,CAAC,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,cAAc,GACrB,kBAAkB,CA4LpB;AAGD,mBAAmB,SAAS,CAAC"}