@upstart.gg/vite-plugins 0.1.68 → 0.1.70

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,4 +1,46 @@
 import { sendToParent } from "./utils.js";
+import { getLabels } from "./labels.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 = getLabels().recoveryTitle;
+  title.style.cssText = "margin: 0 0 0.5rem; font-size: 1.1rem; font-weight: 600;";
+  const text = document.createElement("p");
+  text.textContent = getLabels().recoveryText;
+  text.style.cssText = "margin: 0 0 1.25rem; font-size: 0.9rem; color: #555;";
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = getLabels().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
@@ -6,7 +48,12 @@ export function initErrorHandler() {
     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/form-guard.ts

@@ -1,10 +1,11 @@
+import { getLabels } from "./labels.js";
+
 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
@@ -99,7 +100,7 @@ function ensureTooltip(): HTMLDivElement {
   if (tooltip) return tooltip;
   tooltip = document.createElement("div");
   tooltip.id = "upstart-form-guard-tooltip";
-  tooltip.textContent = TOOLTIP_MESSAGE;
+  tooltip.textContent = getLabels().formGuard;
 
   let css =
     "background: #111827; color: #fff; font-size: 12px; line-height: 1.3; " +

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,11 +1,13 @@
 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";
 import { sendToParent } from "./utils.js";
 import { getCurrentMode, setCurrentMode, clearSelection, removeSelection, getSelection } from "./state.js";
+import { setLabels } from "./labels.js";
 import type { EditorMode, UpstartParentMessage } from "./types.js";
 
 let isInitialized = false;
@@ -146,6 +148,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 +201,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) {
@@ -240,6 +249,8 @@ function handleParentMessage(event: MessageEvent): void {
     const el = removeSelection(message.key);
     el?.removeAttribute("data-upstart-selected");
     sendToParent({ type: "selection-changed", selection: getSelection() });
+  } else if (message.type === "set-labels") {
+    setLabels(message.labels);
   }
 }
 

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

@@ -0,0 +1,77 @@
+/**
+ * User-facing labels of the editor runtime. The runtime runs inside the previewed site,
+ * which has no access to the dashboard's i18n catalogs: the editor sends the translated
+ * labels through a `set-labels` message once the runtime is ready, and everything the
+ * runtime renders reads them lazily via {@link getLabels}. English is the fallback.
+ */
+export interface RuntimeLabels {
+  newItem: string;
+  keepItem: string;
+  removeItem: string;
+  addItem: string;
+  applyChanges: string;
+  dragToReorder: string;
+  clickToEdit: string;
+  startTyping: string;
+  recoveryTitle: string;
+  recoveryText: string;
+  refresh: string;
+  formGuard: string;
+  bold: string;
+  italic: string;
+  strikethrough: string;
+  inlineCode: string;
+  heading: string;
+  blockquote: string;
+  bulletList: string;
+  orderedList: string;
+}
+
+export const DEFAULT_LABELS: Readonly<RuntimeLabels> = Object.freeze({
+  newItem: "New item",
+  keepItem: "Keep item",
+  removeItem: "Remove item",
+  addItem: "Add item",
+  applyChanges: "Apply changes",
+  dragToReorder: "Drag to reorder",
+  clickToEdit: "Click to edit...",
+  startTyping: "Start typing...",
+  recoveryTitle: "The preview needs a refresh",
+  recoveryText: "Your changes are saved. Refresh the preview to keep editing.",
+  refresh: "Refresh",
+  formGuard: "This action isn’t available in the editor preview",
+  bold: "Bold",
+  italic: "Italic",
+  strikethrough: "Strikethrough",
+  inlineCode: "Inline Code",
+  heading: "Heading",
+  blockquote: "Blockquote",
+  bulletList: "Bullet List",
+  orderedList: "Ordered List",
+});
+
+let labels: RuntimeLabels = { ...DEFAULT_LABELS };
+
+/** Current labels (translated once the editor sent them, English before that). */
+export function getLabels(): Readonly<RuntimeLabels> {
+  return labels;
+}
+
+/**
+ * Override labels with the ones received from the editor. Unknown keys and non-string
+ * values are ignored so a malformed message can never blank a control.
+ */
+export function setLabels(input: unknown): void {
+  if (typeof input !== "object" || input === null) return;
+  const next: RuntimeLabels = { ...labels };
+  for (const key of Object.keys(DEFAULT_LABELS) as (keyof RuntimeLabels)[]) {
+    const value = (input as Record<string, unknown>)[key];
+    if (typeof value === "string" && value.length > 0) next[key] = value;
+  }
+  labels = next;
+}
+
+/** Back to the English defaults (used by tests). */
+export function resetLabels(): void {
+  labels = { ...DEFAULT_LABELS };
+}

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

@@ -4,6 +4,7 @@ import Placeholder from "@tiptap/extension-placeholder";
 import StarterKit from "@tiptap/starter-kit";
 import { sendToParent } from "./utils.js";
 import type { EditorInstance, TextEditorMode, UpstartEditorOptions } from "./types.js";
+import { getLabels, type RuntimeLabels } from "./labels.js";
 
 /**
  * Custom Document node for inline elements (e.g. <a>, <span>, headings).
@@ -247,6 +248,11 @@ const styleCache = new WeakMap<
   { outline: string; outlineOffset: string; cursor: string; transition: string }
 >();
 let resolvedOptions: Required<UpstartEditorOptions> = DEFAULT_OPTIONS;
+
+/** The site may override the placeholder; the default one follows the editor's language. */
+function placeholderFor(options: Required<UpstartEditorOptions>): string {
+  return options.placeholder === DEFAULT_OPTIONS.placeholder ? getLabels().startTyping : options.placeholder;
+}
 let shortcutsRegistered = false;
 let domObserver: MutationObserver | null = null;
 let reactivateTimer: number | null = null;
@@ -335,11 +341,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);
@@ -429,7 +449,7 @@ function createPlainTextEditor(element: HTMLElement, options: Required<UpstartEd
         horizontalRule: false,
       }),
       Placeholder.configure({
-        placeholder: "Click to edit...",
+        placeholder: getLabels().clickToEdit,
       }),
     ],
     content,
@@ -462,7 +482,7 @@ function createRichTextEditor(element: HTMLElement, options: Required<UpstartEdi
   const extensions: Extension[] = [
     StarterKit,
     Placeholder.configure({
-      placeholder: options.placeholder,
+      placeholder: placeholderFor(options),
     }),
   ];
 
@@ -522,7 +542,7 @@ function createInlineRichTextEditor(element: HTMLElement, options: Required<Upst
       horizontalRule: false,
     }),
     Placeholder.configure({
-      placeholder: "Click to edit...",
+      placeholder: getLabels().clickToEdit,
     }),
   ];
 
@@ -579,7 +599,7 @@ function createDirectEditor(element: HTMLElement, options: Required<UpstartEdito
       codeBlock: false,
       horizontalRule: false,
     }),
-    Placeholder.configure({ placeholder: "Click to edit..." }),
+    Placeholder.configure({ placeholder: getLabels().clickToEdit }),
   ];
 
   if (options.bubbleMenu) {
@@ -615,7 +635,10 @@ function createRichPanelEditor(element: HTMLElement, options: Required<UpstartEd
   let hasChanged = false;
 
   const bubbleMenuElement = createBubbleMenuElement("inline");
-  const extensions: Extension[] = [StarterKit, Placeholder.configure({ placeholder: options.placeholder })];
+  const extensions: Extension[] = [
+    StarterKit,
+    Placeholder.configure({ placeholder: placeholderFor(options) }),
+  ];
 
   if (options.bubbleMenu) {
     extensions.push(BubbleMenu.configure({ element: bubbleMenuElement }));
@@ -944,20 +967,20 @@ function restoreStyles(element: HTMLElement): void {
   element.style.transition = cached.transition;
 }
 
-const BUBBLE_MENU_GROUPS: { command: string; icon: string; title: string }[][] = [
+const BUBBLE_MENU_GROUPS: { command: string; icon: string; label: keyof RuntimeLabels }[][] = [
   [
-    { command: "bold", icon: "format-bold", title: "Bold" },
-    { command: "italic", icon: "format-italic", title: "Italic" },
-    { command: "strike", icon: "format-strikethrough", title: "Strikethrough" },
-    { command: "code", icon: "code-tags", title: "Inline Code" },
+    { command: "bold", icon: "format-bold", label: "bold" },
+    { command: "italic", icon: "format-italic", label: "italic" },
+    { command: "strike", icon: "format-strikethrough", label: "strikethrough" },
+    { command: "code", icon: "code-tags", label: "inlineCode" },
   ],
   [
-    { command: "heading", icon: "format-header-1", title: "Heading" },
-    { command: "blockquote", icon: "format-quote-close", title: "Blockquote" },
+    { command: "heading", icon: "format-header-1", label: "heading" },
+    { command: "blockquote", icon: "format-quote-close", label: "blockquote" },
   ],
   [
-    { command: "bulletList", icon: "format-list-bulleted", title: "Bullet List" },
-    { command: "orderedList", icon: "format-list-numbered", title: "Ordered List" },
+    { command: "bulletList", icon: "format-list-bulleted", label: "bulletList" },
+    { command: "orderedList", icon: "format-list-numbered", label: "orderedList" },
   ],
 ];
 
@@ -982,7 +1005,8 @@ function createBubbleMenuElement(mode: "block" | "inline" = "block"): HTMLDivEle
       menu.appendChild(separator);
     }
 
-    for (const { command, icon, title } of group) {
+    for (const { command, icon, label } of group) {
+      const title = getLabels()[label];
       const button = document.createElement("button");
       button.type = "button";
       button.dataset.command = command;

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

@@ -6,6 +6,9 @@ import type {
   PayloadArrayItemDelete,
   PayloadArraySet,
 } from "~/upstart-editor-api";
+import type { RuntimeLabels } from "./labels.js";
+
+export type { RuntimeLabels } from "./labels.js";
 
 /**
  * Editor mode
@@ -109,6 +112,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";
@@ -140,7 +149,9 @@ export type ParentMessage =
   | { type: "request-scroll-position" }
   | { type: "restore-scroll-position"; x: number; y: number }
   | { type: "clear-selection" }
-  | { type: "deselect"; key: string };
+  | { type: "deselect"; key: string }
+  /** Translated labels for the controls the runtime renders (see `runtime/labels.ts`). */
+  | { type: "set-labels"; labels: Partial<RuntimeLabels> };
 
 /**
  * Message wrapper sent via postMessage from iframe.