@base44-preview/vite-plugin 0.2.26-pr.43.b670203 → 0.2.27-pr.41.77be9cb

package/src/injections/visual-edit-agent/README.md

@@ -0,0 +1,222 @@
+# Visual Edit Agent - Modular Architecture
+
+The visual edit agent has been refactored into a clean, modular structure with proper separation of concerns.
+
+## Directory Structure
+
+```
+src/injections/visual-edit-agent/
+├── index.ts                           # Main entry point & setup orchestration
+├── constants.ts                       # Shared constants
+├── state/
+│   └── agent-state.ts                # Centralized state management
+├── ui/
+│   └── overlay.ts                    # Overlay creation, positioning & selection helpers
+├── utils/
+│   └── dom-utils.ts                  # DOM helpers (position, viewport, classes)
+├── handlers/
+│   ├── hover-handlers.ts             # Mouse hover interactions
+│   ├── click-handlers.ts             # Element selection & click handling
+│   ├── inline-edit-handlers.ts       # Bridges to inline editing capability
+│   ├── message-handlers.ts           # Parent window message handling
+│   └── messages/
+│       ├── types.ts                  # Message type enums & interfaces
+│       ├── toggle-visual-edit-mode.ts # Handles toggle-visual-edit-mode
+│       └── toggle-inline-edit-mode.ts # Handles toggle-inline-edit-mode
+└── capabilities/
+    └── inline-editing/               # Inline text editing capability
+        ├── index.ts                  # Public API
+        ├── core.ts                   # ContentEditable logic
+        ├── validation.ts             # Element eligibility checks
+        ├── styles.ts                 # CSS injection / removal
+        └── README.md                 # Documentation
+```
+
+## Module Responsibilities
+
+### `index.ts` - Setup & Orchestration
+- Initializes the visual edit agent
+- Sets up all event listeners
+- Creates mutation observers
+- Coordinates between different modules
+
+### `constants.ts` - Configuration
+- Defines all magic numbers and styling constants
+- Single source of truth for configuration values
+- Easy to modify behavior without touching logic
+
+### `state/agent-state.ts` - State Management
+- **`AgentState` interface**: TypeScript interface defining all state
+- **`createAgentState()`**: Factory function to create initial state
+- Centralizes all state in one place for easier debugging
+
+### `ui/overlay.ts` - UI Components & Overlay State Helpers
+- **`createOverlay()`**: Creates hover/selection overlay elements
+- **`positionOverlay()`**: Positions a single overlay relative to an element
+- **`clearOverlays()`**: Removes overlay elements from the DOM
+- **`clearSelection(state)`**: Removes `data-selected`, clears selected overlays, and nulls `selectedElementId` — single source of truth for deselection used by `unselectElement`, `handleElementSelection`, and `toggleVisualEditMode`
+- **`repositionSelectedOverlays(state)`**: Re-positions all selected overlays after layout changes
+- **`repositionHoverOverlays(state)`**: Re-positions all hover overlays after layout changes
+
+### `handlers/hover-handlers.ts` - Hover Interactions
+- **`handleMouseOver()`**: Shows hover overlays on element hover
+- **`handleMouseOut()`**: Clears hover overlays
+- **`clearHoverOverlays()`**: Cleanup utility
+- Manages the hover state and visual feedback
+
+### `handlers/click-handlers.ts` - Selection Logic
+- **`handleElementClick()`**: Main click event handler
+- **`handleElementSelection()`**: Handles first click (selection)
+- Manages the selection flow and second-click inline editing trigger
+- Sends `element-selected` messages to parent
+
+### `handlers/inline-edit-handlers.ts` - Inline Editing
+- **`handleEnterInlineEditingMode()`**: Enables contentEditable
+- **`handleClearInlineEditingMode()`**: Disables contentEditable
+- **`setupInlineEditCallback()`**: Wires up text input handler
+- **Debounced reporting**: 500ms debounce for `inline-edit` messages
+- Bridges between visual edit agent and the inline-editing capability
+
+### `capabilities/inline-editing/` - Inline Editing Capability
+Reusable inline text editing using contentEditable.
+- **`core.ts`**: Main contentEditable logic — `enterInlineEditingMode` injects the focus-suppression CSS; `clearInlineEditingMode` removes it automatically
+- **`validation.ts`**: Element eligibility checks
+- **`styles.ts`**: CSS injection (`injectFocusOutlineCSS`) and removal (`removeFocusOutlineCSS`)
+- **`README.md`**: Complete documentation
+- See [capabilities/inline-editing/README.md](./capabilities/inline-editing/README.md) for details
+
+### `handlers/messages/` - Per-Message Handlers
+Split out of `message-handlers.ts` to keep each handler focused:
+- **`types.ts`**: `IncomingMessageType` / `OutgoingMessageType` enums and all message interfaces
+- **`toggle-visual-edit-mode.ts`**: Enables/disables visual edit mode, clears all overlays & selection via `clearSelection`, updates the inline-edit experiment flag
+- **`toggle-inline-edit-mode.ts`**: Programmatically enters/exits inline editing for a given element
+
+### `handlers/message-handlers.ts` - Parent Communication
+- **`handleMessage()`**: Switch-board for all incoming messages — delegates to per-message handlers above
+- **`handleScroll()`**: Sends `element-position-update` to parent on scroll
+- **`handleResize()`**: Calls `repositionSelectedOverlays` + `repositionHoverOverlays` on resize
+- **`updateElementClassesAndReposition()`**: Updates classes & repositions overlays after CSS reflow
+- **`updateElementContent()`**: Updates element `innerText` & repositions overlays
+- **`unselectElement()`**: Exits inline editing if active, then delegates to `clearSelection`
+- Central hub for all parent-iframe communication
+
+## State Flow
+
+```
+User Action
+    ↓
+Handler (e.g., handleElementClick)
+    ↓
+Modifies State (AgentState)
+    ↓
+Updates UI (overlay.ts)
+    ↓
+Sends Message to Parent (window.parent.postMessage)
+```
+
+## Position Update Strategy
+
+Following Framewire's reactive pattern, we **update positions at the source** instead of using a broad MutationObserver. This is more performant and predictable.
+
+### Position Updates Happen:
+1. **Element Selection** - When user clicks an element
+2. **Inline Editing** - During text input (debounced)
+3. **Scroll Events** - Via scroll listener
+4. **Window Resize** - Via resize listener  
+5. **Parent Updates** - When parent sends class/content changes (with 50ms delay for CSS reflow)
+6. **Hover Events** - When user hovers over elements
+
+See [POSITION_UPDATES.md](./POSITION_UPDATES.md) for detailed analysis.
+
+## Key Features
+
+### 1. **Separation of Concerns**
+Each module has a single, well-defined responsibility
+
+### 2. **Shared Helpers Over Repeated Logic**
+Overlay repositioning and selection clearing live in `overlay.ts` as named helpers (`repositionSelectedOverlays`, `repositionHoverOverlays`, `clearSelection`) rather than being duplicated across handler files
+
+### 3. **Centralized State**
+All state is in `AgentState`, passed to handlers explicitly
+
+### 4. **Type Safety**
+TypeScript interfaces define clear contracts between modules
+
+### 5. **Easy to Extend**
+Adding new handlers or message types is straightforward
+
+### 6. **Better Debugging**
+Smaller files and clear responsibilities make debugging easier
+
+## Message Types
+
+### Incoming (from Parent)
+- `toggle-visual-edit-mode` - Enable/disable visual edit mode + experiment flags
+- `update-classes` - Update element classes
+- `update-content` - Update element text content
+- `unselect-element` - Clear current selection
+- `refresh-page` - Reload the page
+- `toggle-inline-edit-mode` - Programmatically enable/disable inline editing
+- `request-element-position` - Request position of selected element
+- `popover-drag-state` - Notify about popover drag state
+- `dropdown-state` - Notify about dropdown open state
+
+### Outgoing (to Parent)
+- `visual-edit-agent-ready` - Agent initialized and ready
+- `element-selected` - Element was selected
+- `element-position-update` - Selected element position changed
+- `content-editing-started` - Inline editing began
+- `inline-edit` - Debounced content change during editing
+- `content-editing-ended` - Inline editing finished
+- `close-dropdowns` - Request to close dropdowns
+
+## Inline Editing Experiment
+
+Inline editing is gated behind an experiment flag: `specs.newInlineEditEnabled`
+
+**Enable via:**
+```typescript
+{
+  type: "toggle-visual-edit-mode",
+  data: {
+    enabled: true,
+    specs: {
+      newInlineEditEnabled: true
+    }
+  }
+}
+```
+
+**When enabled:**
+- Second click on selected text element enters inline edit mode
+- `toggle-inline-edit-mode` messages work
+- 500ms debounced `inline-edit` messages sent during typing
+
+**When disabled:**
+- Second click does nothing
+- `toggle-inline-edit-mode` messages ignored
+
+## Constants
+
+All configurable values are in `constants.ts`:
+
+```typescript
+INLINE_EDIT_DEBOUNCE_MS = 500          // Debounce time for inline edits
+OVERLAY_Z_INDEX = "9999"                // Z-index for overlays
+SELECTED_BORDER_COLOR = "#2563EB"       // Selected element border color
+HOVER_BORDER_COLOR = "#95a5fc"          // Hover element border color
+REPOSITION_DELAY_MS = 50                // Delay before repositioning overlays
+// ... and more
+```
+
+## Usage
+
+Import and call the setup function:
+
+```typescript
+import { setupVisualEditAgent } from './visual-edit-agent.js';
+
+setupVisualEditAgent();
+```
+
+That's it! The agent will initialize, set up all listeners, and start responding to messages.

package/src/injections/visual-edit-agent/capabilities/inline-editing/core.ts

@@ -0,0 +1,120 @@
+import { injectFocusOutlineCSS, removeFocusOutlineCSS } from "./styles.js";
+import { selectText, isEditableTextElement } from "./validation.js";
+
+/**
+ * Callback function type for handling text input changes
+ */
+type OnTextInputChange = (element: HTMLElement) => void;
+
+/**
+ * Global callback that gets triggered on every input event
+ * This is set by the visual-edit-agent and includes both updatePosition and reportInlineEdit
+ */
+let onTextInputChangeCallback: OnTextInputChange | null = null;
+
+/**
+ * Set the callback function that will be called on text input changes
+ */
+export function setInlineEditCallback(callback: OnTextInputChange | null): void {
+  onTextInputChangeCallback = callback;
+}
+
+/**
+ * WeakMap to track AbortControllers for each element's input listener.
+ * Using WeakMap ensures no memory leaks — when an element is garbage collected,
+ * its entry is automatically removed.
+ */
+const listenerAbortControllers = new WeakMap<HTMLElement, AbortController>();
+
+/**
+ * Internal handler for the native input event
+ */
+function handleInputEvent(this: HTMLElement, e: Event): void {
+  if (onTextInputChangeCallback) {
+    onTextInputChangeCallback(this);
+  }
+}
+
+/**
+ * Check if an element should enter inline editing mode
+ * Called when user clicks on an already-selected element
+ */
+export function shouldEnterInlineEditingMode(element: Element): boolean {
+  // Must have data-selected="true"
+  if (!(element instanceof HTMLElement) || element.dataset.selected !== "true") {
+    return false;
+  }
+
+  // Must pass all editability checks
+  if (!isEditableTextElement(element)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Enable contentEditable mode on an element
+ * Follows the exact flow from inlineEdit.md
+ */
+export function enterInlineEditingMode(element: HTMLElement): void {
+  // Inject CSS to suppress focus outline
+  injectFocusOutlineCSS();
+
+  // Store original state
+  element.dataset.originalTextContent = element.textContent || "";
+  element.dataset.originalCursor = element.style.cursor;
+
+  // Enable contentEditable
+  element.contentEditable = "true";
+
+  // Create an AbortController to manage the input listener lifecycle
+  const abortController = new AbortController();
+  listenerAbortControllers.set(element, abortController);
+
+  // Add input event listener with AbortSignal for automatic cleanup
+  element.addEventListener("input", handleInputEvent, { signal: abortController.signal });
+
+  // Set cursor to text
+  element.style.cursor = "text";
+
+  // Select all text
+  selectText(element);
+
+  // Focus after render
+  setTimeout(() => {
+    element.focus();
+  }, 0);
+}
+
+/**
+ * Disable contentEditable mode on an element
+ * Reverses everything done by enterInlineEditingMode
+ */
+export function clearInlineEditingMode(element: HTMLElement): void {
+  // Abort the input event listener using the stored AbortController
+  const abortController = listenerAbortControllers.get(element);
+  if (abortController) {
+    abortController.abort();
+    listenerAbortControllers.delete(element);
+  }
+
+  // If element was removed from DOM before cleanup, skip DOM operations
+  if (!element.isConnected) {
+    return;
+  }
+
+  removeFocusOutlineCSS();
+
+  // Disable contentEditable
+  element.contentEditable = "false";
+
+  // Remove stored original text content
+  delete element.dataset.originalTextContent;
+
+  // Restore original cursor
+  if (element.dataset.originalCursor !== undefined) {
+    element.style.cursor = element.dataset.originalCursor;
+    delete element.dataset.originalCursor;
+  }
+}

package/src/injections/visual-edit-agent/capabilities/inline-editing/index.ts

@@ -0,0 +1,10 @@
+export {
+  enterInlineEditingMode,
+  clearInlineEditingMode,
+  shouldEnterInlineEditingMode,
+  setInlineEditCallback,
+} from "./core.js";
+
+export { injectFocusOutlineCSS, removeFocusOutlineCSS } from "./styles.js";
+
+export { isEditableTextElement, isStaticArrayTextElement, selectText } from "./validation.js";

package/src/injections/visual-edit-agent/capabilities/inline-editing/styles.ts

@@ -0,0 +1,26 @@
+/**
+ * Inject CSS to suppress the browser's default focus outline on contentEditable elements
+ */
+export function injectFocusOutlineCSS(): void {
+  const existingStyle = document.getElementById("visual-edit-focus-styles");
+  if (existingStyle) return;
+
+  const style = document.createElement("style");
+  style.id = "visual-edit-focus-styles";
+  style.textContent = `
+    [data-selected="true"][contenteditable="true"]:focus {
+      outline: none !important;
+    }
+  `;
+  document.head.appendChild(style);
+}
+
+/**
+ * Remove the injected focus outline CSS
+ */
+export function removeFocusOutlineCSS(): void {
+  const style = document.getElementById("visual-edit-focus-styles");
+  if (style) {
+    style.remove();
+  }
+}

package/src/injections/visual-edit-agent/capabilities/inline-editing/validation.ts

@@ -0,0 +1,87 @@
+/**
+ * Select all text content in an element using the Selection API
+ */
+export function selectText(element: HTMLElement): void {
+  const range = document.createRange();
+  range.selectNodeContents(element);
+  const selection = window.getSelection();
+  selection?.removeAllRanges();
+  selection?.addRange(range);
+}
+
+/**
+ * Check if an element is a static array text element.
+ * These elements are "dynamic" (they reference item.field) but their source
+ * is a compile-time static array, so they can be safely edited inline.
+ */
+export function isStaticArrayTextElement(element: HTMLElement): boolean {
+  return !!element.dataset.arrField;
+}
+
+const ALLOWED_INLINE_EDIT_TAGS = [
+  "div",
+  "p",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "span",
+  "li",
+  "td",
+  "a",
+  "button",
+  "label",
+];
+
+/**
+ * Structural checks shared by both regular and static-array inline editing:
+ * allowed tag, non-empty text, no media children, leaf node.
+ */
+function passesStructuralChecks(element: HTMLElement): boolean {
+  if (!ALLOWED_INLINE_EDIT_TAGS.includes(element.tagName.toLowerCase())) {
+    return false;
+  }
+
+  const textContent = element.textContent?.trim() || "";
+  if (textContent.length === 0) {
+    return false;
+  }
+
+  if (element.querySelector("img, video, canvas, svg") !== null) {
+    return false;
+  }
+
+  if (element.children.length > 0) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if an element is an editable text element
+ * Based on the eligibility rules from inlineEdit.md (non-dynamic only),
+ * with an exception for static array elements.
+ */
+export function isEditableTextElement(element: Element): boolean {
+  if (!(element instanceof HTMLElement)) {
+    return false;
+  }
+
+  if (!passesStructuralChecks(element)) {
+    return false;
+  }
+
+  // Static array elements are editable even though they are technically "dynamic"
+  if (isStaticArrayTextElement(element)) {
+    return true;
+  }
+
+  if (element.dataset.dynamicContent === "true") {
+    return false;
+  }
+
+  return true;
+}

package/src/injections/visual-edit-agent/constants.ts

@@ -0,0 +1,9 @@
+export const INLINE_EDIT_DEBOUNCE_MS = 500;
+export const OVERLAY_TRANSITION = "all 0.1s ease-in-out";
+export const OVERLAY_Z_INDEX = "9999";
+export const SELECTED_BORDER_COLOR = "#2563EB";
+export const HOVER_BORDER_COLOR = "#95a5fc";
+export const HOVER_BACKGROUND_COLOR = "rgba(99, 102, 241, 0.05)";
+export const LABEL_TOP_OFFSET = "-27px";
+export const LABEL_LEFT_OFFSET = "-2px";
+export const REPOSITION_DELAY_MS = 50;

package/src/injections/visual-edit-agent/handlers/click-handlers.ts

@@ -0,0 +1,146 @@
+import type { AgentState } from "../state/agent-state.js";
+import { OutgoingMessageType } from "./messages/types.js";
+import { findElementsById } from "../../utils.js";
+import { createOverlay, positionOverlay, clearSelection } from "../ui/overlay.js";
+import { clearHoverOverlays } from "./hover-handlers.js";
+import { shouldEnterInlineEditingMode } from "../capabilities/inline-editing/index.js";
+import { handleClearInlineEditingMode, handleEnterInlineEditingMode } from "./inline-edit-handlers.js";
+import { getElementPosition, getElementClasses } from "../utils/dom-utils.js";
+
+/**
+ * Handle element selection (first click)
+ */
+export function handleElementSelection(
+  state: AgentState,
+  element: Element,
+  visualSelectorId: string | null
+): void {
+  if (state.currentEditingElement) {
+    handleClearInlineEditingMode(state);
+  }
+  clearSelection(state);
+
+  // Find all elements with the same ID
+  const elements = findElementsById(visualSelectorId);
+
+  if (state.isInlineEditExperimentEnabled) {
+    elements.forEach((el) => {
+      if (el instanceof HTMLElement) {
+        el.dataset.selected = "true";
+      }
+    });
+  }
+
+  // Create selected overlays for all matching elements
+  elements.forEach((el) => {
+    const overlay = createOverlay(true);
+    document.body.appendChild(overlay);
+    state.selectedOverlays.push(overlay);
+    positionOverlay(overlay, el, true, state.isVisualEditMode);
+  });
+
+  state.selectedElementId = visualSelectorId;
+
+  // Clear hover overlays
+  clearHoverOverlays(state);
+
+  // Send message to parent window with element info
+  const htmlElement = element as HTMLElement;
+
+  // Resolve static-array context from vite-plugin attributes (data-arr-*)
+  const arrEl = htmlElement.closest("[data-arr-variable-name]") as HTMLElement | null;
+  const staticArrayName = arrEl?.dataset?.arrVariableName || null;
+  const rawIdx = arrEl?.dataset?.arrIndex;
+  const staticArrayIndex = rawIdx != null ? parseInt(rawIdx, 10) : null;
+  const staticArrayField = htmlElement.dataset?.arrField || null;
+
+  const elementData = {
+    type: OutgoingMessageType.ELEMENT_SELECTED,
+    tagName: element.tagName,
+    classes: getElementClasses(element),
+    visualSelectorId: visualSelectorId,
+    content: htmlElement.innerText,
+    dataSourceLocation: htmlElement.dataset.sourceLocation,
+    isDynamicContent: htmlElement.dataset.dynamicContent === "true",
+    linenumber: htmlElement.dataset.linenumber,
+    filename: htmlElement.dataset.filename,
+    position: getElementPosition(element.getBoundingClientRect()),
+    staticArrayName,
+    staticArrayIndex,
+    staticArrayField,
+  };
+  window.parent.postMessage(elementData, "*");
+}
+
+/**
+ * Handle element click
+ */
+export function handleElementClick(state: AgentState, e: MouseEvent): void {
+  if (!state.isVisualEditMode) return;
+
+  const target = e.target as Element;
+
+  // Bail out early if clicking on a contentEditable element (allow normal editing)
+  if (state.isInlineEditExperimentEnabled && target instanceof HTMLElement && target.contentEditable === "true") {
+    return;
+  }
+
+  // If currently editing, clicking outside should exit editing mode
+  if (state.currentEditingElement) {
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+    handleClearInlineEditingMode(state);
+    return;
+  }
+
+  // Close dropdowns when clicking anywhere in iframe if a dropdown is open
+  if (state.isDropdownOpen) {
+    e.preventDefault();
+    e.stopPropagation();
+    e.stopImmediatePropagation();
+
+    window.parent.postMessage({ type: OutgoingMessageType.CLOSE_DROPDOWNS }, "*");
+    return;
+  }
+
+  // Prevent clicking on SVG path elements
+  if (target.tagName.toLowerCase() === "path") {
+    return;
+  }
+
+  // Prevent default behavior immediately when in visual edit mode
+  e.preventDefault();
+  e.stopPropagation();
+  e.stopImmediatePropagation();
+
+  // Support both data-source-location and data-visual-selector-id
+  const element = target.closest(
+    "[data-source-location], [data-visual-selector-id]"
+  );
+  if (!element) {
+    return;
+  }
+
+  const htmlElement = element as HTMLElement;
+  const visualSelectorId =
+    htmlElement.dataset.sourceLocation ||
+    htmlElement.dataset.visualSelectorId;
+
+  // Check if this element is already selected (second click scenario)
+  const isAlreadySelected =
+    state.selectedElementId === visualSelectorId &&
+    htmlElement.dataset.selected === "true";
+
+  if (isAlreadySelected) {
+    // Second click on already-selected element: check if it should enter inline editing
+    // Only if the experiment is enabled
+    if (state.isInlineEditExperimentEnabled && shouldEnterInlineEditingMode(htmlElement)) {
+      handleEnterInlineEditingMode(state, htmlElement);
+      return;
+    }
+  }
+
+  // First click: select the element
+  handleElementSelection(state, element, visualSelectorId || null);
+}