@upstart.gg/vite-plugins 0.1.67 → 0.1.69

package/src/upstart-editor-api.ts

@@ -352,6 +352,13 @@ export const payloadEditClassName = z.object({
   action: z.literal("editClassName"),
   id: z.string().min(1),
   className: z.string(),
+  /**
+   * className currently rendered in the preview for this element. Registry ids are
+   * `file:offset`, so an earlier edit in the same file followed by a rebuild renames the ids
+   * while the preview (not reloaded) keeps the old ones: this lets the server find the element
+   * again by its content instead of failing on the stale id.
+   */
+  previousClassName: z.string().optional(),
 });
 
 export type PayloadEditClassName = z.infer<typeof payloadEditClassName>;
@@ -654,7 +661,7 @@ export class UpstartEditorAPI {
     if (!parsed.success) {
       return { success: false, error: `Invalid payload: ${parsed.error.message}` };
     }
-    const { id, className: newClassName } = parsed.data;
+    const { id, className: newClassName, previousClassName } = parsed.data;
     if (!this.registry) {
       try {
         await this.loadRegistry();
@@ -663,16 +670,75 @@ export class UpstartEditorAPI {
       }
     }
 
-    const entry = this.registry!.elements[id];
-    if (!entry) {
-      return { success: false, error: `Element ${id} not found in registry` };
-    }
+    const resolved = await this.resolveClassNameEntry(id, previousClassName);
+    if ("error" in resolved) return { success: false, error: resolved.error };
+    return this.applyEdit(resolved.id, resolved.entry, newClassName);
+  }
 
-    if (entry.type !== "className") {
-      return { success: false, error: `Element ${id} is not a className element (type: ${entry.type})` };
+  /**
+   * Find the registry entry to edit for a className write. The id is authoritative when its
+   * entry still holds the className the preview shows. Otherwise the id is stale — an earlier
+   * edit in the same file shifted the offsets and a rebuild regenerated the registry with new
+   * ids, while the preview kept the old ones — and the element is looked up by its current
+   * className: first among the registry entries of the file (nearest to the old offset), then
+   * by a raw search of the source. Without `previousClassName` the old behaviour applies.
+   */
+  private async resolveClassNameEntry(
+    id: string,
+    previousClassName: string | undefined,
+  ): Promise<{ id: string; entry: EditableEntry } | { error: string }> {
+    const elements = this.registry!.elements;
+    const entry = elements[id];
+    if (entry && entry.type !== "className") {
+      return { error: `Element ${id} is not a className element (type: ${entry.type})` };
+    }
+    if (previousClassName === undefined || (entry && entry.originalContent === previousClassName)) {
+      return entry ? { id, entry } : { error: `Element ${id} not found in registry` };
+    }
+
+    const sep = id.lastIndexOf(":");
+    const file = sep === -1 ? (entry?.file ?? "") : id.slice(0, sep);
+    const wantedOffset = sep === -1 ? 0 : Number(id.slice(sep + 1)) || 0;
+    const byDistance = (a: number, b: number) => Math.abs(a - wantedOffset) - Math.abs(b - wantedOffset);
+
+    // Same className in the (regenerated) registry, nearest to where the element used to be.
+    const candidates = Object.entries(elements)
+      .filter(([, e]) => e.file === file && e.type === "className" && e.originalContent === previousClassName)
+      .sort(([, a], [, b]) => byDistance(a.startOffset, b.startOffset));
+    if (candidates[0]) return { id: candidates[0][0], entry: candidates[0][1] };
+
+    // Registry stale as well: look for the literal in the source itself.
+    if (file && previousClassName !== "") {
+      try {
+        const code = await fs.readFile(path.join(this.projectRoot, file), "utf-8");
+        const starts: number[] = [];
+        for (let i = code.indexOf(previousClassName); i !== -1; i = code.indexOf(previousClassName, i + 1)) {
+          const before = code[i - 1];
+          const after = code[i + previousClassName.length];
+          if ((before === '"' || before === "'" || before === "`") && after === before) starts.push(i);
+        }
+        starts.sort(byDistance);
+        if (starts[0] !== undefined) {
+          const found: EditableEntry = {
+            file,
+            type: "className",
+            startOffset: starts[0],
+            endOffset: starts[0] + previousClassName.length,
+            originalContent: previousClassName,
+            context: entry?.context ?? { parentTag: "unknown" },
+          };
+          // Registered under the id the preview uses so follow-up edits resolve directly.
+          elements[id] = found;
+          return { id, entry: found };
+        }
+      } catch {
+        // Unreadable file: fall through to the registry entry (if any).
+      }
     }
 
-    return this.applyEdit(id, entry, newClassName);
+    // The preview's className may include runtime-added classes: trust the entry, which
+    // applyEdit still validates against the file content.
+    return entry ? { id, entry } : { error: `Element ${id} not found in registry` };
   }
 
   /**

package/src/vite-plugin-upstart-attrs.ts

@@ -330,7 +330,50 @@ export function transformWithOxc(code: string, filePath: string) {
           ? buildI18nAttributeValue(jsxNode, allI18nKeys, state.code, state, state.constants)
           : null;
 
-        if (hasI18n && i18nAttrValue && (!isMixed || i18nAffixes)) {
+        // A single <Trans> next to element siblings without text (an <Icon>, an <svg>…): the
+        // plain editor replaces the whole content of the editable element, so making the
+        // container editable would destroy the icon, and React would later fight over it
+        // (Iconify swaps its placeholder <span> for the <svg> once the icon data is loaded).
+        // Wrap the <Trans> in its own editable <span> instead; the container stays untouched.
+        const directTransNodes = jsxNode.children.filter(
+          (c) =>
+            c.type === "JSXElement" && detectTransComponent(c as JSXElement, state.code, state.constants),
+        ) as JSXElement[];
+        const elementSiblings = jsxNode.children.filter(
+          (c) =>
+            c.type === "JSXElement" && !detectTransComponent(c as JSXElement, state.code, state.constants),
+        );
+        const transToWrap =
+          hasI18n &&
+          i18nAttrValue &&
+          !isMixed &&
+          transChildren.length === 1 &&
+          tCallChildren.length === 0 &&
+          directTransNodes.length === 1 &&
+          elementSiblings.length > 0 &&
+          hasRange(directTransNodes[0])
+            ? directTransNodes[0]
+            : null;
+
+        if (transToWrap) {
+          const wrapperHash = hashContent(state.code.slice(transToWrap.start, transToWrap.end));
+          const loopSuffixes = state.loopStack.map((l) => (l.indexName ? `\${${l.indexName}}` : "0"));
+          const wrapperAttrs = [
+            loopSuffixes.length > 0
+              ? `data-upstart-hash={\`${wrapperHash}-${loopSuffixes.join("-")}\`}`
+              : `data-upstart-hash="${wrapperHash}"`,
+            'data-upstart-editable-text="true"',
+            'data-upstart-editable-text-mode="plain"',
+            `data-upstart-i18n=${i18nAttrValue}`,
+          ];
+          const wrapperValueKeys = [...new Set(allI18nKeys.flatMap((t) => t.valueKeys ?? []))];
+          if (wrapperValueKeys.length > 0) {
+            wrapperAttrs.push(`data-i18n-values="${wrapperValueKeys.join(",")}"`);
+          }
+          state.s.appendLeft(transToWrap.start, `<span ${wrapperAttrs.join(" ")}>`);
+          state.s.appendRight(transToWrap.end, "</span>");
+          modified = true;
+        } else if (hasI18n && i18nAttrValue && (!isMixed || i18nAffixes)) {
           attributes.push('data-upstart-editable-text="true"');
           attributes.push('data-upstart-editable-text-mode="plain"');
 

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

@@ -1,4 +1,5 @@
 import { getCurrentMode, getSelection, toggleSelection } from "./state.js";
+import { pickImagesForClick, type Point } from "./image-pick.js";
 import { sendToParent } from "./utils.js";
 import type { EditableImageRef, SelectionRef } from "./types.js";
 
@@ -59,26 +60,33 @@ function toImageRef(node: HTMLElement): EditableImageRef {
   };
 }
 
+function editableImagesIn(el: HTMLElement): HTMLElement[] {
+  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);
+  }
+  return Array.from(found);
+}
+
 /**
- * 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.
+ * Collect the editable images (elements carrying data-upstart-image-id) relevant to a click
+ * on `start`: the images inside the clicked element, or, when it has none, an ancestor's image
+ * lying under the click point (a hero <img> covered by an overlay). See pickImagesForClick for
+ * the exact rules — in particular an ancestor's images are never surfaced when the click is
+ * not visually on them, so clicking a title never opens the logo next to it.
  */
-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(toImageRef);
+function collectImages(start: HTMLElement, point?: Point): EditableImageRef[] {
+  const withRect = (node: HTMLElement) => ({ node, rect: node.getBoundingClientRect() });
+  const own = editableImagesIn(start).map(withRect);
+  const ancestorLevels: { node: HTMLElement; rect: DOMRect }[][] = [];
+  if (own.length === 0) {
+    let el = start.parentElement;
+    for (let depth = 0; el && el !== document.body && depth < 8; depth++, el = el.parentElement) {
+      ancestorLevels.push(editableImagesIn(el).map(withRect));
     }
   }
-  return [];
+  return pickImagesForClick(own, ancestorLevels, point).map(({ node }) => toImageRef(node));
 }
 
 /**
@@ -209,6 +217,8 @@ function handleClick(event: MouseEvent): void {
     console.warn("[Upstart Editor] Click target is not an HTMLElement");
     return;
   }
+  // Viewport coordinates of the click, to tell which image (if any) was visually hit.
+  const clickPoint: Point = { x: event.clientX, y: event.clientY };
 
   if (mode === "select") {
     handleSelectClick(event, target);
@@ -264,7 +274,7 @@ function handleClick(event: MouseEvent): void {
           themeColors,
           bounds: { top: 0, left: 0, width: 0, height: 0, right: 0, bottom: 0 },
           tagName: editableEl.tagName.toLowerCase(),
-          images: collectImages(editableEl),
+          images: collectImages(editableEl, clickPoint),
         });
       }
     }
@@ -299,7 +309,7 @@ function handleClick(event: MouseEvent): void {
         themeColors: {},
         bounds: { top: 0, left: 0, width: 0, height: 0, right: 0, bottom: 0 },
         tagName: datasourceEl.tagName.toLowerCase(),
-        images: collectImages(datasourceEl),
+        images: collectImages(datasourceEl, clickPoint),
       });
       return;
     }
@@ -377,7 +387,7 @@ function handleClick(event: MouseEvent): void {
     bounds,
     viewportWidth: window.innerWidth,
     tagName: element.tagName.toLowerCase(),
-    images: collectImages(element),
+    images: collectImages(element, clickPoint),
   });
 
   console.log("[Upstart Editor] Element clicked:", componentName, hash);

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

@@ -0,0 +1,67 @@
+/**
+ * Makes React's DOM reconciliation survive the editor's own DOM mutations.
+ *
+ * In edit mode the text editor replaces the children of React-managed elements with a
+ * TipTap view. When React later re-renders one of those subtrees (an interaction of the
+ * site, a revalidation, a language switch…) it references child nodes that are gone and
+ * `insertBefore` / `removeChild` throw `NotFoundError`, which unmounts the whole page into
+ * the site's error boundary. Tolerating those two calls keeps the page alive: an insert
+ * whose reference node is gone becomes an append, and removing a node that is no longer a
+ * child is a no-op. The first time it happens `onDesync` is called so the editor can offer
+ * a refresh, as the preview may now differ slightly from the source.
+ */
+export interface DomLike {
+  insertBefore: <T extends Node>(this: Node, node: T, child: Node | null) => T;
+  removeChild: <T extends Node>(this: Node, child: T) => T;
+}
+
+function describeNode(node: Node | null): string {
+  if (!node) return "null";
+  if (node.nodeType === 3) return `#text "${(node.textContent ?? "").slice(0, 40)}"`;
+  const el = node as Element;
+  if (!el.tagName) return node.nodeName;
+  const id = el.id ? `#${el.id}` : "";
+  const cls =
+    typeof el.className === "string" && el.className
+      ? `.${el.className.split(/\s+/).slice(0, 3).join(".")}`
+      : "";
+  const hash = (el as HTMLElement).dataset?.upstartHash
+    ? ` [hash=${(el as HTMLElement).dataset.upstartHash}]`
+    : "";
+  return `<${el.tagName.toLowerCase()}${id}${cls}>${hash}`;
+}
+
+export function installDomGuard(proto: DomLike, onDesync: () => void): void {
+  const originalInsertBefore = proto.insertBefore;
+  const originalRemoveChild = proto.removeChild;
+  let reported = false;
+  // Every tolerated call is logged with its stack: that is what tells which update (React
+  // reconciliation, a library…) touched an element the editor had modified. Open the
+  // preview iframe's console context in the devtools to read it.
+  const report = (operation: string, parent: Node, node: Node, child: Node | null) => {
+    console.warn(
+      `[Upstart Editor] DOM out of sync: ${operation} on ${describeNode(parent)} with ${describeNode(node)}` +
+        (child ? ` before ${describeNode(child)} (no longer a child)` : " (no longer a child)"),
+      { parent, node, child, stack: new Error("DOM out of sync").stack },
+    );
+    if (reported) return;
+    reported = true;
+    onDesync();
+  };
+
+  proto.insertBefore = function <T extends Node>(this: Node, node: T, child: Node | null): T {
+    if (child && child.parentNode !== this) {
+      report("insertBefore", this, node, child);
+      return originalInsertBefore.call(this, node, null) as T;
+    }
+    return originalInsertBefore.call(this, node, child) as T;
+  };
+
+  proto.removeChild = function <T extends Node>(this: Node, child: T): T {
+    if (child.parentNode !== this) {
+      report("removeChild", this, child, null);
+      return child;
+    }
+    return originalRemoveChild.call(this, child) as T;
+  };
+}

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

@@ -1,12 +1,58 @@
 import { sendToParent } from "./utils.js";
 
+/** Errors thrown by React's DOM reconciliation once the editor mutated its nodes. */
+const RECONCILIATION_ERROR_RE =
+  /insertBefore|removeChild|appendChild|Minified React error #(?:418|422|423|425)/;
+
+const OVERLAY_ID = "upstart-preview-recovery";
+
+/**
+ * Full-screen notice inside the preview asking the user to refresh, shown when the page
+ * could not be kept alive (React crashed into the site's error boundary). Reloading the
+ * iframe re-syncs the DOM with the source and the editor's registry.
+ */
+export function showRecoveryOverlay(): void {
+  if (document.getElementById(OVERLAY_ID)) return;
+  const overlay = document.createElement("div");
+  overlay.id = OVERLAY_ID;
+  overlay.setAttribute("role", "alertdialog");
+  overlay.style.cssText =
+    "position: fixed; inset: 0; z-index: 2147483647; display: flex; align-items: center; justify-content: center; " +
+    "background: rgba(17, 17, 27, 0.72); font-family: system-ui, sans-serif; color: #111;";
+  const card = document.createElement("div");
+  card.style.cssText =
+    "max-width: 24rem; margin: 1rem; padding: 1.5rem; border-radius: 0.75rem; background: #fff; " +
+    "box-shadow: 0 20px 50px rgba(0,0,0,0.3); text-align: center;";
+  const title = document.createElement("p");
+  title.textContent = "The preview needs a refresh";
+  title.style.cssText = "margin: 0 0 0.5rem; font-size: 1.1rem; font-weight: 600;";
+  const text = document.createElement("p");
+  text.textContent = "Your changes are saved. Refresh the preview to keep editing.";
+  text.style.cssText = "margin: 0 0 1.25rem; font-size: 0.9rem; color: #555;";
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = "Refresh";
+  button.style.cssText =
+    "padding: 0.6rem 1.4rem; border: 0; border-radius: 9999px; background: #7270c6; color: #fff; " +
+    "font-weight: 600; font-size: 0.95rem; cursor: pointer;";
+  button.addEventListener("click", () => window.location.reload());
+  card.append(title, text, button);
+  overlay.append(card);
+  (document.body ?? document.documentElement).append(overlay);
+}
+
 export function initErrorHandler() {
   // Global error handler for uncaught errors in the editor
   window.addEventListener("error", (event) => {
     console.error("[Upstart Editor] Uncaught error in editor:", event.error);
     sendToParent({
       type: "editor-error",
-      error: event.error,
+      error: String(event.error?.message ?? event.message ?? event.error),
     });
+    const message = String(event.error?.message ?? event.message ?? "");
+    if (RECONCILIATION_ERROR_RE.test(message)) {
+      sendToParent({ type: "editor-desync", fatal: true });
+      showRecoveryOverlay();
+    }
   });
 }

package/src/vite-plugin-upstart-editor/runtime/image-pick.ts

@@ -0,0 +1,40 @@
+export type Point = { x: number; y: number };
+export type Rect = { top: number; left: number; width: number; height: number };
+
+export function rectContainsPoint(rect: Rect, point: Point): boolean {
+  return (
+    point.x >= rect.left &&
+    point.x <= rect.left + rect.width &&
+    point.y >= rect.top &&
+    point.y <= rect.top + rect.height
+  );
+}
+
+/**
+ * Images to surface in the inspector for a click. Pure so it can be unit-tested without a DOM.
+ *
+ * - `own` are the editable images inside the clicked element (the element itself included):
+ *   they belong to what was clicked, so they are all candidates. When the click lands on one
+ *   of them, only that one is kept, so a card with several images doesn't open them all when
+ *   the user clearly targeted one.
+ * - `ancestorLevels` are the images of each successive ancestor (nearest first), used only for
+ *   the "hero covered by an overlay" case: the click is on a sibling overlay, but visually on
+ *   the image. Only images under the click point qualify, otherwise clicking a navbar title
+ *   would surface the logo, and clicking any element would surface every image on the page.
+ */
+export function pickImagesForClick<T extends { rect: Rect }>(
+  own: T[],
+  ancestorLevels: T[][],
+  point: Point | undefined,
+): T[] {
+  if (own.length > 0) {
+    const underPoint = point ? own.filter((img) => rectContainsPoint(img.rect, point)) : [];
+    return underPoint.length > 0 ? underPoint : own;
+  }
+  if (!point) return [];
+  for (const level of ancestorLevels) {
+    const underPoint = level.filter((img) => rectContainsPoint(img.rect, point));
+    if (underPoint.length > 0) return underPoint;
+  }
+  return [];
+}

package/src/vite-plugin-upstart-editor/runtime/index.ts

@@ -1,6 +1,7 @@
 import { initClickHandler } from "./click-handler.js";
 import { initHoverOverlay, hideOverlays } from "./hover-overlay.js";
 import { initErrorHandler } from "./error-handler.js";
+import { installDomGuard } from "./dom-guard.js";
 import { initTextEditor, activateAllEditors, destroyAllActiveEditors } from "./text-editor.js";
 import { initArrayControls, refreshArrayControls, hideArrayControls } from "./array-controls.js";
 import { initFormGuard } from "./form-guard.js";
@@ -146,6 +147,10 @@ export function initUpstartEditor(): void {
           i18next.getResource(i18next.language, namespace, key) as string | undefined
       : undefined;
 
+    // Marks the document as running inside the editor preview (the site's error boundary
+    // uses it to offer a refresh instead of a raw error).
+    document.documentElement.setAttribute("data-upstart-editor", "");
+    installDomGuard(Node.prototype, () => sendToParent({ type: "editor-desync", fatal: false }));
     initTextEditor(getRawI18nTemplate ? { getRawI18nTemplate } : {});
     initClickHandler();
     initHoverOverlay();
@@ -195,6 +200,9 @@ function handleParentMessage(event: MessageEvent): void {
     if (el) {
       el.className = message.className;
     }
+    // No `previewCSS` at all means "patch the className only": the editor uses it after a save
+    // to sync the DOM with the file without touching the current CSS preview.
+    if (message.previewCSS === undefined) return;
     const STYLE_ID = "upstart-preview-style";
     let styleEl = document.getElementById(STYLE_ID) as HTMLStyleElement | null;
     if (message.previewCSS) {

package/src/vite-plugin-upstart-editor/runtime/text-editor.ts

@@ -335,11 +335,25 @@ export function destroyAllActiveEditors(): void {
   }
 }
 
+/** Descendants the plain editor cannot reproduce: taking over the element would destroy them. */
+const PLAIN_EDITOR_FOREIGN_CHILDREN = "svg, img, picture, video, iframe, canvas";
+
 function setupEditableElement(element: HTMLElement, options: Required<UpstartEditorOptions>): void {
   const hash = getEditableHash(element);
   if (!hash || activeEditors.has(element)) {
     return;
   }
+  // Older builds may still mark a container holding an icon next to its text as editable:
+  // the plain editor would wipe the icon and React would later fight over it. Leave such
+  // elements alone (the current plugin wraps the text in its own <span> instead).
+  if (getEditorMode(element, options) === "plain" && element.querySelector(PLAIN_EDITOR_FOREIGN_CHILDREN)) {
+    console.warn(
+      "[Upstart Editor] Skipping text editor on an element that also holds media/icons:",
+      element.dataset.upstartHash,
+      element,
+    );
+    return;
+  }
 
   cacheStyles(element);
   activateEditor(element, hash, options);

package/src/vite-plugin-upstart-editor/runtime/types.ts

@@ -109,6 +109,12 @@ export type EditorMessage =
   | { type: "editor-route"; routeId: string }
   | { type: "scroll-position"; x: number; y: number }
   | { type: "editor-error"; error: string }
+  /**
+   * React's DOM reconciliation hit nodes the editor had replaced. `fatal: false`: the page was
+   * kept alive by the DOM guard (a refresh is advisable); `fatal: true`: the page crashed and
+   * the preview shows its recovery overlay.
+   */
+  | { type: "editor-desync"; fatal: boolean }
   | { type: "selection-changed"; selection: SelectionRef[] }
   | {
       type: "element-clicked";