@upstart.gg/vite-plugins 0.1.41 → 0.1.42

package/src/vite-plugin-upstart-editor/runtime/array-controls.ts

@@ -0,0 +1,478 @@
+import { getCurrentMode } from "./state.js";
+import { sendToParent } from "./utils.js";
+
+// Editor-only controls for inline-array .map() lists. Add/delete are staged LOCALLY
+// (no server round-trip per action): "×" marks an item for removal, "+" inserts an
+// editable draft pill, and a green "✓" below the "+" commits the whole batch at once
+// via a single `arraySet` edit + rebuild. Per-item text editing stays live; arraySet
+// reads the current item texts from the DOM so live edits are preserved.
+
+const DEFAULT_NEW_ITEM = "New item";
+const DRAFT_ATTR = "data-upstart-draft-item";
+
+// Layout of the "+"/"✓" stack placed to the right of a list.
+const BTN_SIZE = 22;
+const STACK_GAP = 6; // vertical gap between "+" and "✓"
+const BUTTON_MARGIN = 12; // left margin between the item and the buttons
+
+let layer: HTMLDivElement | null = null;
+let observer: MutationObserver | null = null;
+let resizeObserver: ResizeObserver | null = null;
+let rafId: number | null = null;
+let isInitialized = false;
+let isMutatingDom = false;
+
+// Items observed for size changes (e.g. text edits widen a pill) so the "×" stays
+// anchored to the item's corner. WeakSet keeps observe() calls idempotent.
+const observedForResize = new WeakSet<Element>();
+
+// arrayId -> set of original item indices currently marked for deletion.
+const pendingDeletes = new Map<string, Set<number>>();
+
+// In-progress drag (reorder). Tracked at document level so it survives overlay
+// rebuilds; the overlay is frozen while a drag is active.
+let drag: { arrayId: string; node: HTMLElement } | null = null;
+
+// The list item currently hovered — its per-item "×"/"⠿" controls are the only
+// ones shown (others stay hidden until hovered). buttonOwner lets a button keep its
+// item "hovered" while the pointer sits on the button (which overlays the corner).
+let hoveredItem: HTMLElement | null = null;
+const buttonOwner = new WeakMap<HTMLElement, HTMLElement>();
+
+export function initArrayControls(): void {
+  if (typeof document === "undefined" || isInitialized) return;
+  isInitialized = true;
+
+  window.addEventListener("scroll", scheduleRefresh, { passive: true, capture: true });
+  window.addEventListener("resize", scheduleRefresh, { passive: true });
+  document.addEventListener("mouseover", onHoverMove, { passive: true });
+
+  observer = new MutationObserver((mutations) => {
+    if (isMutatingDom) return;
+    for (const m of mutations) {
+      const t = m.target as Node;
+      if (layer && (t === layer || layer.contains(t))) continue;
+      scheduleRefresh();
+      return;
+    }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+
+  if (typeof ResizeObserver !== "undefined") {
+    resizeObserver = new ResizeObserver(() => scheduleRefresh());
+  }
+}
+
+// Append a per-item button and record which item it belongs to, so hovering the
+// button (which overlays the item's corner) keeps that item considered hovered.
+function appendOwned(root: HTMLElement, btn: HTMLElement, owner: HTMLElement): void {
+  buttonOwner.set(btn, owner);
+  root.appendChild(btn);
+}
+
+// Track the hovered list item; refresh when it changes so its controls toggle.
+function onHoverMove(e: MouseEvent): void {
+  if (getCurrentMode() !== "edit") return;
+  const owner = hoverOwner(e.target as HTMLElement | null);
+  if (owner !== hoveredItem) {
+    hoveredItem = owner;
+    scheduleRefresh();
+  }
+}
+
+// The list item under the pointer: either the item itself (or a descendant), or a
+// per-item control button that belongs to one.
+function hoverOwner(target: HTMLElement | null): HTMLElement | null {
+  if (!target) return null;
+  const item = target.closest<HTMLElement>(`[data-upstart-array-id]:not([${DRAFT_ATTR}]), [${DRAFT_ATTR}]`);
+  if (item) return item;
+  if (layer?.contains(target)) {
+    const owner = buttonOwner.get(target);
+    if (owner && document.contains(owner)) return owner;
+  }
+  return null;
+}
+
+// Observe an item once so the overlay re-anchors when the item resizes.
+function observeResize(el: Element): void {
+  if (resizeObserver && !observedForResize.has(el)) {
+    observedForResize.add(el);
+    resizeObserver.observe(el);
+  }
+}
+
+export function refreshArrayControls(): void {
+  if (typeof document === "undefined") return;
+
+  if (getCurrentMode() !== "edit") {
+    hideArrayControls();
+    return;
+  }
+
+  // While dragging we move list nodes live; keep the overlay frozen and rebuild it
+  // once on drop (the drag is driven by document-level listeners, not the overlay).
+  if (drag) return;
+
+  isMutatingDom = true;
+  try {
+    const root = ensureLayer();
+    root.replaceChildren();
+
+    // Group original (non-draft) items by array id, ordered by loop index.
+    const groups = new Map<string, HTMLElement[]>();
+    for (const el of document.querySelectorAll<HTMLElement>("[data-upstart-array-id]")) {
+      if (el.hasAttribute(DRAFT_ATTR)) continue;
+      const id = el.dataset.upstartArrayId;
+      if (!id) continue;
+      (groups.get(id) ?? groups.set(id, []).get(id)!).push(el);
+    }
+
+    for (const [arrayId, items] of groups) {
+      items.sort((a, b) => itemIndex(a) - itemIndex(b));
+      const deletes = pendingDeletes.get(arrayId) ?? new Set<number>();
+      const drafts = draftPillsFor(arrayId);
+      const ordered = orderedItemsFor(arrayId);
+      // Reordering only makes sense with more than one item.
+      const draggable = ordered.length > 1;
+
+      // Original items: per-item controls show only on hover; a marked item always
+      // keeps its restore "×" (it has pointer-events:none, so it can't be hovered).
+      for (const item of items) {
+        observeResize(item);
+        const idx = itemIndex(item);
+        const marked = deletes.has(idx);
+        applyDeletionStyle(item, marked);
+        if (!marked && item !== hoveredItem) continue;
+        const rect = item.getBoundingClientRect();
+        if (draggable && !marked) appendOwned(root, makeDragHandle(arrayId, item, rect), item);
+        appendOwned(root, makeItemDeleteButton(arrayId, idx, marked, rect), item);
+      }
+
+      // Draft (added) pills: controls show on hover; each has its own "×".
+      for (const pill of drafts) {
+        observeResize(pill);
+        if (pill !== hoveredItem) continue;
+        const rect = pill.getBoundingClientRect();
+        if (draggable) appendOwned(root, makeDragHandle(arrayId, pill, rect), pill);
+        appendOwned(root, makeDraftRemoveButton(pill, rect), pill);
+      }
+
+      // "+" (and "✓" when there are pending changes) after the last item in DOM
+      // order, as a vertically-centred stack with a small left margin.
+      const anchor = ordered[ordered.length - 1];
+      if (!anchor) continue;
+      const a = anchor.getBoundingClientRect();
+
+      const finalCount = items.length - deletes.size + drafts.length;
+      const dirty = deletes.size > 0 || drafts.length > 0 || isReordered(arrayId);
+      const showApply = dirty && finalCount >= 1;
+
+      const stackHeight = showApply ? BTN_SIZE * 2 + STACK_GAP : BTN_SIZE;
+      const left = a.right + window.scrollX + BUTTON_MARGIN;
+      const top = a.top + window.scrollY + (a.height - stackHeight) / 2;
+
+      root.appendChild(makeAddButton(arrayId, top, left));
+      if (showApply) {
+        root.appendChild(makeApplyButton(arrayId, top + BTN_SIZE + STACK_GAP, left));
+      }
+    }
+  } finally {
+    isMutatingDom = false;
+  }
+}
+
+export function hideArrayControls(): void {
+  if (layer) layer.replaceChildren();
+}
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+function ensureLayer(): HTMLDivElement {
+  if (layer) return layer;
+  layer = document.createElement("div");
+  layer.id = "upstart-array-controls";
+  layer.style.cssText =
+    "position: absolute; top: 0; left: 0; width: 0; height: 0; " +
+    "pointer-events: none; z-index: 2147483646;";
+  document.body.appendChild(layer);
+  return layer;
+}
+
+function itemIndex(el: HTMLElement): number {
+  const n = el.dataset.upstartArrayIndex ? Number(el.dataset.upstartArrayIndex) : Number.NaN;
+  return Number.isFinite(n) ? n : 0;
+}
+
+function originalItemsFor(arrayId: string): HTMLElement[] {
+  return [
+    ...document.querySelectorAll<HTMLElement>(
+      `[data-upstart-array-id="${cssAttr(arrayId)}"]:not([${DRAFT_ATTR}])`,
+    ),
+  ].sort((a, b) => itemIndex(a) - itemIndex(b));
+}
+
+function draftPillsFor(arrayId: string): HTMLElement[] {
+  return [...document.querySelectorAll<HTMLElement>(`[${DRAFT_ATTR}="${cssAttr(arrayId)}"]`)];
+}
+
+// All items of an array (originals + drafts) in DOM order — this is the order the
+// list is rendered in and the order applied to the source on ✓.
+function orderedItemsFor(arrayId: string): HTMLElement[] {
+  const sel = `[data-upstart-array-id="${cssAttr(arrayId)}"]:not([${DRAFT_ATTR}]), [${DRAFT_ATTR}="${cssAttr(arrayId)}"]`;
+  return [...document.querySelectorAll<HTMLElement>(sel)];
+}
+
+// True when the original items no longer appear in their source order (i.e. the
+// user has dragged at least one item), so the ✓ apply button should be offered.
+function isReordered(arrayId: string): boolean {
+  let prev = -1;
+  for (const el of orderedItemsFor(arrayId)) {
+    if (el.hasAttribute(DRAFT_ATTR)) continue;
+    const idx = itemIndex(el);
+    if (idx < prev) return true;
+    prev = idx;
+  }
+  return false;
+}
+
+function cssAttr(value: string): string {
+  return value.replace(/["\\]/g, "\\$&");
+}
+
+function textOf(el: HTMLElement): string {
+  return (el.textContent ?? "").trim();
+}
+
+function applyDeletionStyle(item: HTMLElement, marked: boolean): void {
+  if (marked) {
+    item.style.opacity = "0.4";
+    item.style.textDecoration = "line-through";
+    item.style.pointerEvents = "none";
+  } else {
+    item.style.removeProperty("opacity");
+    item.style.removeProperty("text-decoration");
+    item.style.removeProperty("pointer-events");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Buttons
+// ---------------------------------------------------------------------------
+
+// Geometric SVG icons — centred by the flex container + viewBox, so they don't
+// depend on the host page's font metrics (which left text glyphs mis-aligned).
+const ICON_PATHS: Record<string, string> = {
+  plus: '<path d="M12 5v14M5 12h14"/>',
+  cross: '<path d="M6 6 18 18M18 6 6 18"/>',
+  check: '<path d="M5 12.5 10 17.5 19 7"/>',
+  restore: '<path d="M3 4v5h5"/><path d="M3.5 9a8.5 8.5 0 1 0 2.2-3.8L3 9"/>',
+  grip: '<circle cx="9" cy="6" r="1.5"/><circle cx="15" cy="6" r="1.5"/><circle cx="9" cy="12" r="1.5"/><circle cx="15" cy="12" r="1.5"/><circle cx="9" cy="18" r="1.5"/><circle cx="15" cy="18" r="1.5"/>',
+};
+
+function setIcon(btn: HTMLElement, name: keyof typeof ICON_PATHS, px: number): void {
+  const dots = name === "grip";
+  btn.innerHTML =
+    `<svg width="${px}" height="${px}" viewBox="0 0 24 24" ` +
+    `fill="${dots ? "currentColor" : "none"}" stroke="${dots ? "none" : "currentColor"}" ` +
+    'stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" ' +
+    `style="display:block;pointer-events:none">${ICON_PATHS[name]}</svg>`;
+}
+
+function baseButton(top: number, left: number, size: number, bg: string): HTMLButtonElement {
+  const btn = document.createElement("button");
+  btn.type = "button";
+  btn.style.cssText =
+    `position: absolute; top: ${top}px; left: ${left}px; width: ${size}px; height: ${size}px; ` +
+    "padding: 0; display: flex; align-items: center; justify-content: center; " +
+    `background: ${bg}; color: #fff; border: 1px solid #fff; border-radius: 50%; ` +
+    "line-height: 1; cursor: pointer; pointer-events: auto; box-shadow: 0 1px 3px rgba(0,0,0,0.3);";
+  return btn;
+}
+
+function makeItemDeleteButton(
+  arrayId: string,
+  index: number,
+  marked: boolean,
+  rect: DOMRect,
+): HTMLButtonElement {
+  const btn = baseButton(rect.top + window.scrollY - 8, rect.right + window.scrollX - 8, 16, "#ef4444");
+  setIcon(btn, marked ? "restore" : "cross", 10);
+  btn.title = marked ? "Keep item" : "Remove item";
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const set = pendingDeletes.get(arrayId) ?? new Set<number>();
+    if (set.has(index)) set.delete(index);
+    else set.add(index);
+    if (set.size) pendingDeletes.set(arrayId, set);
+    else pendingDeletes.delete(arrayId);
+    refreshArrayControls();
+  });
+  return btn;
+}
+
+function makeDraftRemoveButton(pill: HTMLElement, rect: DOMRect): HTMLButtonElement {
+  const btn = baseButton(rect.top + window.scrollY - 8, rect.right + window.scrollX - 8, 16, "#ef4444");
+  setIcon(btn, "cross", 10);
+  btn.title = "Remove item";
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    pill.remove();
+    refreshArrayControls();
+  });
+  return btn;
+}
+
+function makeAddButton(arrayId: string, top: number, left: number): HTMLButtonElement {
+  const btn = baseButton(top, left, 22, "#7270c6");
+  setIcon(btn, "plus", 14);
+  btn.title = "Add item";
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    addDraftPill(arrayId);
+  });
+  return btn;
+}
+
+function makeApplyButton(arrayId: string, top: number, left: number): HTMLButtonElement {
+  const btn = baseButton(top, left, 22, "#16a34a");
+  setIcon(btn, "check", 13);
+  btn.title = "Apply changes";
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    applyArray(arrayId);
+  });
+  return btn;
+}
+
+// Grip centred on the item's top edge (away from the neighbour's "×" corners);
+// press and drag to reorder.
+function makeDragHandle(arrayId: string, node: HTMLElement, rect: DOMRect): HTMLButtonElement {
+  const top = rect.top + window.scrollY - 8;
+  const left = rect.left + window.scrollX + rect.width / 2 - 8;
+  const btn = baseButton(top, left, 16, "#6b7280");
+  setIcon(btn, "grip", 12);
+  btn.title = "Drag to reorder";
+  btn.style.cursor = "grab";
+  btn.addEventListener("pointerdown", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    startDrag(arrayId, node);
+  });
+  return btn;
+}
+
+// ---------------------------------------------------------------------------
+// Drag to reorder
+// ---------------------------------------------------------------------------
+
+function startDrag(arrayId: string, node: HTMLElement): void {
+  drag = { arrayId, node };
+  node.style.opacity = "0.5";
+  document.body.style.userSelect = "none";
+  // Drive the drag from document level so it survives overlay rebuilds.
+  document.addEventListener("pointermove", onDragMove);
+  document.addEventListener("pointerup", onDragEnd, { once: true });
+}
+
+function onDragMove(e: PointerEvent): void {
+  if (!drag) return;
+  const target = itemUnderPointer(drag.arrayId, e.clientX, e.clientY, drag.node);
+  if (!target) return;
+  const r = target.getBoundingClientRect();
+  // Insert before/after based on the pointer vs the target's horizontal midpoint.
+  if (e.clientX > r.left + r.width / 2) target.after(drag.node);
+  else target.before(drag.node);
+}
+
+function onDragEnd(): void {
+  document.removeEventListener("pointermove", onDragMove);
+  document.body.style.removeProperty("user-select");
+  if (drag) {
+    drag.node.style.removeProperty("opacity");
+    drag = null;
+  }
+  refreshArrayControls();
+}
+
+// The array item (original or draft) whose box contains the pointer, excluding the
+// node being dragged.
+function itemUnderPointer(arrayId: string, x: number, y: number, exclude: HTMLElement): HTMLElement | null {
+  for (const el of orderedItemsFor(arrayId)) {
+    if (el === exclude) continue;
+    const r = el.getBoundingClientRect();
+    if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return el;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+function addDraftPill(arrayId: string): void {
+  const template = originalItemsFor(arrayId)[0] ?? draftPillsFor(arrayId)[0];
+  if (!template?.parentElement) return;
+
+  const pill = template.cloneNode(false) as HTMLElement;
+  // Clone keeps the pill styling (class); strip identity/editor attrs so it is not
+  // picked up by the text editor, click handler, hover overlay or the array query.
+  for (const attr of [...pill.attributes]) {
+    if (attr.name.startsWith("data-upstart-") || attr.name === "contenteditable") {
+      pill.removeAttribute(attr.name);
+    }
+  }
+  pill.removeAttribute("style");
+  pill.setAttribute(DRAFT_ATTR, arrayId);
+  pill.setAttribute("contenteditable", "true");
+  pill.textContent = DEFAULT_NEW_ITEM;
+
+  // Insert after the current last pill of this array (drafts go at the end).
+  const last = draftPillsFor(arrayId).pop() ?? originalItemsFor(arrayId).pop();
+  if (last && last.parentElement === template.parentElement) {
+    last.after(pill);
+  } else {
+    template.parentElement.appendChild(pill);
+  }
+
+  // Focus + select so the user can type the name immediately.
+  pill.focus();
+  const range = document.createRange();
+  range.selectNodeContents(pill);
+  const sel = window.getSelection();
+  sel?.removeAllRanges();
+  sel?.addRange(range);
+
+  refreshArrayControls();
+}
+
+function applyArray(arrayId: string): void {
+  const deletes = pendingDeletes.get(arrayId) ?? new Set<number>();
+  const items: string[] = [];
+
+  // DOM order = the order the user sees (incl. any drag reordering).
+  for (const el of orderedItemsFor(arrayId)) {
+    if (!el.hasAttribute(DRAFT_ATTR) && deletes.has(itemIndex(el))) continue;
+    items.push(textOf(el));
+  }
+
+  if (items.length === 0) return;
+
+  // The server rewrites the whole array, rebuilds + swaps, then the editor reloads
+  // the iframe — which discards the local draft state, so just clear our marks.
+  pendingDeletes.delete(arrayId);
+  sendToParent({ type: "text-edit", payload: { action: "arraySet", arrayId, items } });
+}
+
+function scheduleRefresh(): void {
+  if (rafId !== null) return;
+  rafId = requestAnimationFrame(() => {
+    rafId = null;
+    refreshArrayControls();
+  });
+}

package/src/vite-plugin-upstart-editor/runtime/click-handler.ts

@@ -26,6 +26,41 @@ const DAISY_VAR_NAMES = [
   "error-content",
 ];
 
+interface EditableImageRef {
+  id: string;
+  src: string;
+  alt: string;
+}
+
+/**
+ * Collect editable images (elements carrying data-upstart-image-id) from the
+ * clicked element's nearest subtree. Starting at `start`, we climb ancestors
+ * until we find a subtree that contains at least one editable image. This lets
+ * us surface a background image (e.g. a hero <img> covered by overlays) even
+ * when the click lands on a sibling overlay rather than the image itself.
+ */
+function collectImages(start: HTMLElement): EditableImageRef[] {
+  let el: HTMLElement | null = start;
+  for (let depth = 0; el && el !== document.body && depth < 8; depth++, el = el.parentElement) {
+    const found = new Set<HTMLElement>();
+    if (el.dataset.upstartImageId) found.add(el);
+    for (const node of el.querySelectorAll<HTMLElement>("[data-upstart-image-id]")) {
+      found.add(node);
+    }
+    if (found.size > 0) {
+      return Array.from(found).map((node) => {
+        const img = node as HTMLImageElement;
+        return {
+          id: node.dataset.upstartImageId as string,
+          src: img.currentSrc || img.src || "",
+          alt: img.alt || "",
+        };
+      });
+    }
+  }
+  return [];
+}
+
 /**
  * Initialize click handler for className editing.
  */
@@ -64,6 +99,12 @@ function handleClick(event: MouseEvent): void {
     return;
   }
 
+  // Editor-only chrome (the array ×/+/✓ controls) and locally-staged draft list
+  // items handle their own clicks and must never be treated as element selection.
+  if (target.closest("#upstart-array-controls, [data-upstart-draft-item]")) {
+    return;
+  }
+
   if (target.closest(".upstart-editor-bubble-menu")) {
     console.info("[Upstart Editor] Click ignored: target is inside the bubble menu");
     return;
@@ -139,6 +180,7 @@ function handleClick(event: MouseEvent): void {
         recordId: datasourceEl.dataset.upstartRecordId,
         themeColors: {},
         bounds: { top: 0, left: 0, width: 0, height: 0, right: 0, bottom: 0 },
+        images: collectImages(datasourceEl),
       });
       return;
     }
@@ -215,6 +257,7 @@ function handleClick(event: MouseEvent): void {
     themeColors,
     bounds,
     viewportWidth: window.innerWidth,
+    images: collectImages(element),
   });
 
   console.log("[Upstart Editor] Element clicked:", componentName, hash);

package/src/vite-plugin-upstart-editor/runtime/form-guard.ts

@@ -0,0 +1,121 @@
+let isInitialized = false;
+
+// Methods that don't mutate data and must keep working: GET forms (search /
+// navigation) and method="dialog" (e.g. a modal's close/backdrop buttons).
+const SAFE_METHODS = new Set(["get", "dialog"]);
+
+const TOOLTIP_MESSAGE = "This action isn’t available in the editor preview";
+const TOOLTIP_DURATION_MS = 2500;
+
+// Popover API renders in the browser top layer, so the tooltip sits above modal
+// <dialog>s opened with showModal() (which also live in the top layer and beat any
+// z-index). Fall back to absolute positioning where it isn't supported.
+const SUPPORTS_POPOVER = typeof HTMLElement !== "undefined" && "showPopover" in HTMLElement.prototype;
+
+let tooltip: HTMLDivElement | null = null;
+let tooltipTimer: number | null = null;
+
+/**
+ * Block mutating form submissions inside the previewed site so the user can't
+ * trigger data changes (which only hit the ephemeral preview DB and never persist)
+ * from the editor. This matters most in PREVIEW mode, where the site's buttons are
+ * live — in EDIT mode a click edits the button's text instead of submitting.
+ *
+ * We block the `submit` event rather than disabling buttons: one place covers native
+ * POST forms, React Router <Form>, button clicks and Enter-key submits. The
+ * capture-phase listener + stopImmediatePropagation runs before React's delegated
+ * handler, so React Router never processes the submission; preventDefault blocks a
+ * plain form's POST. GET and dialog submissions are left untouched. When a mutating
+ * submission is blocked, a tooltip on the triggering button explains why.
+ */
+export function initFormGuard(): void {
+  if (typeof document === "undefined" || isInitialized) {
+    return;
+  }
+  isInitialized = true;
+
+  document.addEventListener(
+    "submit",
+    (event: SubmitEvent) => {
+      const form = event.target as HTMLFormElement | null;
+      const method = (
+        event.submitter?.getAttribute("formmethod") ||
+        form?.getAttribute("method") ||
+        "get"
+      ).toLowerCase();
+
+      if (SAFE_METHODS.has(method)) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      console.debug("[Upstart Editor] Blocked a mutating form submission in the editor:", method);
+
+      const anchor = (event.submitter as HTMLElement | null) ?? form;
+      if (anchor) showBlockedTooltip(anchor);
+    },
+    true,
+  );
+}
+
+function showBlockedTooltip(anchor: HTMLElement): void {
+  const tip = ensureTooltip();
+  const rect = anchor.getBoundingClientRect();
+
+  if (SUPPORTS_POPOVER) {
+    // Popover is position:fixed → viewport coordinates (no scroll offset).
+    tip.style.left = `${rect.left + rect.width / 2}px`;
+    tip.style.top = `${rect.top - 8}px`;
+    try {
+      tip.hidePopover();
+    } catch {}
+    try {
+      tip.showPopover();
+    } catch {}
+  } else {
+    tip.style.left = `${rect.left + window.scrollX + rect.width / 2}px`;
+    tip.style.top = `${rect.top + window.scrollY - 8}px`;
+    tip.style.opacity = "1";
+  }
+
+  if (tooltipTimer !== null) {
+    clearTimeout(tooltipTimer);
+  }
+  tooltipTimer = window.setTimeout(() => {
+    tooltipTimer = null;
+    if (!tooltip) return;
+    if (SUPPORTS_POPOVER) {
+      try {
+        tooltip.hidePopover();
+      } catch {}
+    } else {
+      tooltip.style.opacity = "0";
+    }
+  }, TOOLTIP_DURATION_MS);
+}
+
+function ensureTooltip(): HTMLDivElement {
+  if (tooltip) return tooltip;
+  tooltip = document.createElement("div");
+  tooltip.id = "upstart-form-guard-tooltip";
+  tooltip.textContent = TOOLTIP_MESSAGE;
+
+  let css =
+    "background: #111827; color: #fff; font-size: 12px; line-height: 1.3; " +
+    "padding: 6px 10px; border-radius: 6px; max-width: 240px; text-align: center; " +
+    "box-shadow: 0 4px 12px rgba(0,0,0,0.3); pointer-events: none; white-space: normal; " +
+    "transform: translate(-50%, -100%); z-index: 2147483647;";
+
+  if (SUPPORTS_POPOVER) {
+    tooltip.setAttribute("popover", "manual");
+    // Neutralise the UA popover centering so our top/left apply.
+    css += "position: fixed; margin: 0; inset: auto; overflow: visible; border: 0;";
+  } else {
+    css += "position: absolute; opacity: 0; transition: opacity 0.15s ease;";
+  }
+
+  tooltip.style.cssText = css;
+  document.body.appendChild(tooltip);
+  return tooltip;
+}

package/src/vite-plugin-upstart-editor/runtime/hover-overlay.ts

@@ -25,6 +25,7 @@ export function initHoverOverlay(): void {
   style.id = "upstart-hover-edit-styles";
   style.textContent = [
     ":root[data-upstart-edit-mode] [data-upstart-classname-id]:not([data-upstart-editable-text='true']),",
+    ":root[data-upstart-edit-mode] [data-upstart-image-id],",
     ":root[data-upstart-edit-mode] [data-upstart-datasource][data-upstart-record-id]:not([data-upstart-editable-text='true']),",
     ":root[data-upstart-edit-mode] [data-upstart-editor-active] {",
     "  transition: outline 150ms, outline-offset 150ms;",
@@ -69,7 +70,11 @@ export function hideOverlays(): void {
 
 function isEligible(el: HTMLElement): boolean {
   if (el.dataset.upstartEditableText === "true") return false;
-  return !!(el.dataset.upstartClassnameId || (el.dataset.upstartDatasource && el.dataset.upstartRecordId));
+  return !!(
+    el.dataset.upstartClassnameId ||
+    el.dataset.upstartImageId ||
+    (el.dataset.upstartDatasource && el.dataset.upstartRecordId)
+  );
 }
 
 function clearEditableHover(): void {