@upstart.gg/vite-plugins 0.1.68 → 0.1.70

package/dist/vite-plugin-upstart-editor/runtime/types.d.ts

@@ -1,4 +1,5 @@
 import { PayloadArrayItemAdd, PayloadArrayItemDelete, PayloadArraySet, PayloadEditText, PayloadEditTextDirect } from "../../upstart-editor-api.js";
+import { RuntimeLabels } from "./labels.js";
 import { Editor } from "@tiptap/core";
 
 //#region src/vite-plugin-upstart-editor/runtime/types.d.ts
@@ -101,6 +102,15 @@ type EditorMessage = {
 } | {
   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[];
@@ -149,6 +159,9 @@ type ParentMessage = {
 } | {
   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.
@@ -224,5 +237,5 @@ interface UpstartEditorPluginOptions {
   autoInject?: boolean;
 }
 //#endregion
-export { EditableImageRef, EditorInstance, EditorMessage, EditorMode, ElementBounds, ParentMessage, SelectionRef, TextEditorMode, UpstartEditorMessage, UpstartEditorOptions, UpstartEditorPluginOptions, UpstartParentMessage };
+export { EditableImageRef, EditorInstance, EditorMessage, EditorMode, ElementBounds, ParentMessage, type RuntimeLabels, SelectionRef, TextEditorMode, UpstartEditorMessage, UpstartEditorOptions, UpstartEditorPluginOptions, UpstartParentMessage };
 //# sourceMappingURL=types.d.ts.map

package/dist/vite-plugin-upstart-editor/runtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/vite-plugin-upstart-editor/runtime/types.ts"],"mappings":";;;;;;AAeA;;;;KAAY,UAAA;AAOZ;;;;;AAAA,UAAiB,YAAA;EACf,GAAA;EACA,IAAA;EACA,QAAA;EACA,aAAA;EACA,QAAA;EACA,IAAA;EAMS;AAWX;;;;EAXE,SAAA;AAAA;;;;;;;;;KAWU,cAAA;;;AAiBZ;UAZiB,aAAA;EACf,GAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,KAAA;EACA,MAAA;AAAA;;;;UAMe,cAAA;EACf,MAAA,EAAQ,MAAA;EACR,OAAA,EAAS,WAAA;EACT,IAAA;EACA,IAAA,EAAM,cAAA;AAAA;;;;;UAOS,gBAAA;EACf,EAAA;EACA,GAAA;EACA,GAAA;EAKA;EAHA,WAAA;EACA,gBAAA;EAKA;EAHA,KAAA;EACA,MAAA;EACA,YAAA;EACA,aAAA;EAKe;EAHf,OAAA;EASuB;EAPvB,iBAAA;EACA,eAAA;AAAA;;;;KAMU,aAAA;EAEN,IAAA;EACA,OAAA,EACI,eAAA,GACA,qBAAA,GACA,mBAAA,GACA,sBAAA,GACA,eAAA;AAAA;EAEJ,IAAA;EAAsB,IAAA;AAAA;EACtB,IAAA;EAA0B,IAAA;AAAA;EAE1B,IAAA;EAAsB,OAAA;AAAA;EACtB,IAAA;EAAyB,CAAA;EAAW,CAAA;AAAA;EACpC,IAAA;EAAsB,KAAA;AAAA;EACtB,IAAA;EAA2B,SAAA,EAAW,YAAA;AAAA;EAEtC,IAAA;EACA,IAAA;EACA,aAAA;EACA,QAAA;EACA,gBAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA;EACA,WAAA,GAAc,MAAA;EACd,MAAA,EAAQ,aAAA;EACR,aAAA,WAFc;EAId,OAAA,WAHQ;EAKR,MAAA,GAAS,gBAAA;AAAA;;;;KAMH,aAAA;EACN,IAAA;EAAkB,IAAA,EAAM,UAAA;AAAA;EACxB,IAAA;EAA2B,WAAA;EAAqB,SAAA;EAAmB,UAAA;AAAA;EACnE,IAAA;EAAuB,OAAA;EAAiB,GAAA;AAAA;EAExC,IAAA;EAA6B,OAAA;EAAiB,GAAA;AAAA;EAC9C,IAAA;AAAA;EACA,IAAA;EAAiC,CAAA;EAAW,CAAA;AAAA;EAC5C,IAAA;AAAA;EACA,IAAA;EAAkB,GAAA;AAAA;;;;UAKP,oBAAA;EACf,MAAA;EACA,IAAA,EAAM,aAAA;EAAA,CACL,GAAA;AAAA;;;;UAMc,oBAAA;EACf,MAAA;EACA,IAAA,EAAM,aAAA;EAAA,CACL,GAAA;AAAA;;AAMH;;UAAiB,oBAAA;EAAoB;;;;EAKnC,gBAAA;EAyBA;;;;;EAlBA,sBAAA;EA+BoD;AAMtD;;;EA/BE,iBAAA;EA0CU;;;;EApCV,UAAA;;;;;EAMA,WAAA;;;;;EAMA,aAAA;;;;;;EAOA,kBAAA,IAAsB,SAAA,UAAmB,GAAA;AAAA;;;;UAM1B,0BAAA;;;;;EAKf,OAAA;;;;;EAMA,UAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/vite-plugin-upstart-editor/runtime/types.ts"],"mappings":";;;;;;AAkBA;;;;;KAAY,UAAA;;;;;;UAOK,YAAA;EACf,GAAA;EACA,IAAA;EACA,QAAA;EACA,aAAA;EACA,QAAA;EACA,IAAA;EAiBU;;;;;EAXV,SAAA;AAAA;;;;;;;;;KAWU,cAAA;;AAiBZ;;UAZiB,aAAA;EACf,GAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,KAAA;EACA,MAAA;AAAA;;;;UAMe,cAAA;EACf,MAAA,EAAQ,MAAA;EACR,OAAA,EAAS,WAAA;EACT,IAAA;EACA,IAAA,EAAM,cAAA;AAAA;;;;;UAOS,gBAAA;EACf,EAAA;EACA,GAAA;EACA,GAAA;EAMA;EAJA,WAAA;EACA,gBAAA;EAOA;EALA,KAAA;EACA,MAAA;EACA,YAAA;EACA,aAAA;EAWU;EATV,OAAA;;EAEA,iBAAA;EACA,eAAA;AAAA;;;;KAMU,aAAA;EAEN,IAAA;EACA,OAAA,EACI,eAAA,GACA,qBAAA,GACA,mBAAA,GACA,sBAAA,GACA,eAAA;AAAA;EAEJ,IAAA;EAAsB,IAAA;AAAA;EACtB,IAAA;EAA0B,IAAA;AAAA;EAE1B,IAAA;EAAsB,OAAA;AAAA;EACtB,IAAA;EAAyB,CAAA;EAAW,CAAA;AAAA;EACpC,IAAA;EAAsB,KAAA;AAAA;;;;;;;EAMtB,IAAA;EAAuB,KAAA;AAAA;EACvB,IAAA;EAA2B,SAAA,EAAW,YAAA;AAAA;EAEtC,IAAA;EACA,IAAA;EACA,aAAA;EACA,QAAA;EACA,gBAAA;EACA,WAAA;EACA,YAAA;EACA,QAAA;EACA,WAAA,GAAc,MAAA;EACd,MAAA,EAAQ,aAAA;EACR,aAAA,WAIyB;EAFzB,OAAA,WAQmB;EANnB,MAAA,GAAS,gBAAA;AAAA;;;;KAMH,aAAA;EACN,IAAA;EAAkB,IAAA,EAAM,UAAA;AAAA;EACxB,IAAA;EAA2B,WAAA;EAAqB,SAAA;EAAmB,UAAA;AAAA;EACnE,IAAA;EAAuB,OAAA;EAAiB,GAAA;AAAA;EAExC,IAAA;EAA6B,OAAA;EAAiB,GAAA;AAAA;EAC9C,IAAA;AAAA;EACA,IAAA;EAAiC,CAAA;EAAW,CAAA;AAAA;EAC5C,IAAA;AAAA;EACA,IAAA;EAAkB,GAAA;AAAA;EAElB,IAAA;EAAoB,MAAA,EAAQ,OAAA,CAAQ,aAAA;AAAA;;;AAc1C;UATiB,oBAAA;EACf,MAAA;EACA,IAAA,EAAM,aAAA;EAAA,CACL,GAAA;AAAA;;;;UAMc,oBAAA;EACf,MAAA;EACA,IAAA,EAAM,aAAA;EAAA,CACL,GAAA;AAAA;;;;UAMc,oBAAA;EA8Bf;;;;EAzBA,gBAAA;EAsCoD;;AAMtD;;;EArCE,sBAAA;EAgDU;;;;EA1CV,iBAAA;;;;;EAMA,UAAA;;;;;EAMA,WAAA;;;;;EAMA,aAAA;;;;;;EAOA,kBAAA,IAAsB,SAAA,UAAmB,GAAA;AAAA;;;;UAM1B,0BAAA;;;;;EAKf,OAAA;;;;;EAMA,UAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstart.gg/vite-plugins",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "type": "module",
   "files": [
     "dist",
@@ -23,7 +23,7 @@
     "oxc-parser": "0.101.0",
     "unplugin": "^2.3.11",
     "zimmerframe": "^1.1.4",
-    "@upstart.gg/sdk": "^0.1.68"
+    "@upstart.gg/sdk": "^0.1.70"
   },
   "devDependencies": {
     "@rolldown/binding-linux-arm64-gnu": "1.0.0",
@@ -118,7 +118,7 @@
   },
   "peerDependencies": {
     "zod": "4.3.6",
-    "@upstart.gg/sdk": "^0.1.68"
+    "@upstart.gg/sdk": "^0.1.70"
   },
   "author": "Upstart",
   "publishConfig": {

package/src/tests/dom-guard.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test, vi } from "vitest";
+import { installDomGuard, type DomLike } from "../vite-plugin-upstart-editor/runtime/dom-guard";
+
+/** Minimal parent/child model standing in for DOM nodes (vitest runs in node here). */
+class FakeNode {
+  parentNode: FakeNode | null = null;
+  children: FakeNode[] = [];
+}
+
+function makeProto() {
+  const insertBefore = vi.fn(function (this: FakeNode, node: FakeNode, child: FakeNode | null) {
+    const idx = child ? this.children.indexOf(child) : -1;
+    if (child && idx === -1) throw new Error("NotFoundError: insertBefore");
+    if (child) this.children.splice(idx, 0, node);
+    else this.children.push(node);
+    node.parentNode = this;
+    return node;
+  });
+  const removeChild = vi.fn(function (this: FakeNode, child: FakeNode) {
+    const idx = this.children.indexOf(child);
+    if (idx === -1) throw new Error("NotFoundError: removeChild");
+    this.children.splice(idx, 1);
+    child.parentNode = null;
+    return child;
+  });
+  return { insertBefore, removeChild } as unknown as DomLike & { insertBefore: typeof insertBefore };
+}
+
+describe("installDomGuard", () => {
+  test("keeps normal inserts and removals untouched and silent", () => {
+    const proto = makeProto();
+    const onDesync = vi.fn();
+    installDomGuard(proto, onDesync);
+    const parent = new FakeNode();
+    const a = new FakeNode();
+    const b = new FakeNode();
+    (proto.insertBefore as unknown as (this: FakeNode, n: FakeNode, c: FakeNode | null) => FakeNode).call(
+      parent,
+      a,
+      null,
+    );
+    (proto.insertBefore as unknown as (this: FakeNode, n: FakeNode, c: FakeNode | null) => FakeNode).call(
+      parent,
+      b,
+      a,
+    );
+    expect(parent.children).toEqual([b, a]);
+    (proto.removeChild as unknown as (this: FakeNode, c: FakeNode) => FakeNode).call(parent, b);
+    expect(parent.children).toEqual([a]);
+    expect(onDesync).not.toHaveBeenCalled();
+  });
+
+  test("turns an insert before a vanished node into an append and reports once", () => {
+    const proto = makeProto();
+    const onDesync = vi.fn();
+    installDomGuard(proto, onDesync);
+    const parent = new FakeNode();
+    const existing = new FakeNode();
+    parent.children.push(existing);
+    existing.parentNode = parent;
+    const gone = new FakeNode(); // removed by the editor, React still references it
+    const fresh = new FakeNode();
+    const insert = proto.insertBefore as unknown as (
+      this: FakeNode,
+      n: FakeNode,
+      c: FakeNode | null,
+    ) => FakeNode;
+    expect(() => insert.call(parent, fresh, gone)).not.toThrow();
+    expect(parent.children).toEqual([existing, fresh]);
+    expect(() => insert.call(parent, new FakeNode(), gone)).not.toThrow();
+    expect(onDesync).toHaveBeenCalledTimes(1);
+  });
+
+  test("logs every tolerated call with its stack so the culprit can be found", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const proto = makeProto();
+    installDomGuard(proto, () => {});
+    const parent = new FakeNode();
+    const gone = new FakeNode();
+    const remove = proto.removeChild as unknown as (this: FakeNode, c: FakeNode) => FakeNode;
+    remove.call(parent, gone);
+    remove.call(parent, gone);
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(String(warn.mock.calls[0]?.[0])).toContain("DOM out of sync: removeChild");
+    expect(warn.mock.calls[0]?.[1]).toMatchObject({ parent, node: gone });
+    expect(String((warn.mock.calls[0]?.[1] as { stack: string }).stack)).toContain("DOM out of sync");
+    warn.mockRestore();
+  });
+
+  test("ignores the removal of a node that is no longer a child", () => {
+    const proto = makeProto();
+    const onDesync = vi.fn();
+    installDomGuard(proto, onDesync);
+    const parent = new FakeNode();
+    const gone = new FakeNode();
+    const remove = proto.removeChild as unknown as (this: FakeNode, c: FakeNode) => FakeNode;
+    expect(remove.call(parent, gone)).toBe(gone);
+    expect(onDesync).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tests/editor-labels.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, test } from "vitest";
+import {
+  DEFAULT_LABELS,
+  getLabels,
+  resetLabels,
+  setLabels,
+} from "../vite-plugin-upstart-editor/runtime/labels";
+
+describe("editor runtime labels", () => {
+  afterEach(() => resetLabels());
+
+  test("starts with the English defaults", () => {
+    expect(getLabels()).toEqual(DEFAULT_LABELS);
+  });
+
+  test("overrides only the provided keys", () => {
+    setLabels({ addItem: "Ajouter un élément", clickToEdit: "Cliquez pour modifier..." });
+    expect(getLabels().addItem).toBe("Ajouter un élément");
+    expect(getLabels().clickToEdit).toBe("Cliquez pour modifier...");
+    expect(getLabels().removeItem).toBe(DEFAULT_LABELS.removeItem);
+  });
+
+  test("ignores unknown keys, empty strings and non-string values", () => {
+    setLabels({ addItem: "", removeItem: 42, unknown: "x" });
+    expect(getLabels()).toEqual(DEFAULT_LABELS);
+    expect("unknown" in getLabels()).toBe(false);
+  });
+
+  test("ignores malformed payloads", () => {
+    setLabels(null);
+    setLabels("labels");
+    expect(getLabels()).toEqual(DEFAULT_LABELS);
+  });
+
+  test("resetLabels restores the defaults", () => {
+    setLabels({ refresh: "Rafraîchir" });
+    resetLabels();
+    expect(getLabels().refresh).toBe(DEFAULT_LABELS.refresh);
+  });
+});

package/src/tests/image-pick.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { pickImagesForClick, rectContainsPoint } from "../vite-plugin-upstart-editor/runtime/image-pick";
+
+const img = (id: string, left: number, top: number, size = 100) => ({
+  id,
+  rect: { left, top, width: size, height: size },
+});
+
+describe("rectContainsPoint", () => {
+  test("includes edges", () => {
+    const rect = { left: 10, top: 10, width: 20, height: 20 };
+    expect(rectContainsPoint(rect, { x: 10, y: 10 })).toBe(true);
+    expect(rectContainsPoint(rect, { x: 30, y: 30 })).toBe(true);
+    expect(rectContainsPoint(rect, { x: 31, y: 20 })).toBe(false);
+  });
+});
+
+describe("pickImagesForClick", () => {
+  test("a clicked element without images does not surface a sibling image (navbar title vs logo)", () => {
+    const logo = img("logo", 0, 0, 40);
+    expect(pickImagesForClick([], [[logo], [logo]], { x: 200, y: 20 })).toEqual([]);
+  });
+
+  test("a click visually on a hero covered by an overlay surfaces that hero", () => {
+    const hero = img("hero", 0, 0, 800);
+    expect(pickImagesForClick([], [[], [hero]], { x: 400, y: 300 })).toEqual([hero]);
+  });
+
+  test("ancestors never surface every image on the page", () => {
+    const a = img("a", 0, 0);
+    const b = img("b", 500, 500);
+    expect(pickImagesForClick([], [[a, b]], { x: 550, y: 550 })).toEqual([b]);
+    expect(pickImagesForClick([], [[a, b]], { x: 300, y: 300 })).toEqual([]);
+  });
+
+  test("images inside the clicked element are all candidates, narrowed to the one under the click", () => {
+    const a = img("a", 0, 0);
+    const b = img("b", 200, 0);
+    // Click on the container's padding: both images belong to what was clicked.
+    expect(pickImagesForClick([a, b], [], { x: 150, y: 50 })).toEqual([a, b]);
+    // Click on image b itself.
+    expect(pickImagesForClick([a, b], [], { x: 250, y: 50 })).toEqual([b]);
+  });
+
+  test("without a click point, own images are returned and ancestors are ignored", () => {
+    const a = img("a", 0, 0);
+    expect(pickImagesForClick([a], [], undefined)).toEqual([a]);
+    expect(pickImagesForClick([], [[a]], undefined)).toEqual([]);
+  });
+});

package/src/tests/upstart-editor-api.test.ts

@@ -170,6 +170,81 @@ describe("UpstartEditorAPI", () => {
       expect(updatedContent).toBe(`<div className="px-8 py-4 bg-blue-500">Hello</div>`);
     });
 
+    test("resolves a stale id by previousClassName once the registry was regenerated", async () => {
+      // A previous edit enlarged the parent's className, so the rebuild moved the image's
+      // className literal (and its `file:offset` id) while the preview still uses the old id.
+      const sourceContent = `<div className="wrap overflow-hidden"><img className="img object-cover" /></div>`;
+      const sourcePath = path.join(tempDir, "test.tsx");
+      await fs.writeFile(sourcePath, sourceContent);
+      const imgStart = sourceContent.indexOf("img object-cover");
+      const registry: EditableRegistry = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        elements: {
+          "test.tsx:15": {
+            file: "test.tsx",
+            type: "className",
+            startOffset: 16,
+            endOffset: 36,
+            originalContent: "wrap overflow-hidden",
+            context: { parentTag: "div" },
+          },
+          [`test.tsx:${imgStart - 1}`]: {
+            file: "test.tsx",
+            type: "className",
+            startOffset: imgStart,
+            endOffset: imgStart + "img object-cover".length,
+            originalContent: "img object-cover",
+            context: { parentTag: "img" },
+          },
+        },
+      };
+      await fs.writeFile(registryPath, JSON.stringify(registry));
+
+      const result = await api.editClassName({
+        action: "editClassName",
+        id: "test.tsx:40", // the image's id before the rebuild
+        className: "img object-cover object-[50%_30%]",
+        previousClassName: "img object-cover",
+      });
+
+      expect(result.success).toBe(true);
+      const updated = await fs.readFile(sourcePath, "utf-8");
+      expect(updated).toBe(
+        `<div className="wrap overflow-hidden"><img className="img object-cover object-[50%_30%]" /></div>`,
+      );
+    });
+
+    test("falls back to a source search when neither the id nor the registry know the className", async () => {
+      const sourceContent = `<img className="img object-cover" />`;
+      const sourcePath = path.join(tempDir, "test.tsx");
+      await fs.writeFile(sourcePath, sourceContent);
+      const registry: EditableRegistry = { version: 1, generatedAt: new Date().toISOString(), elements: {} };
+      await fs.writeFile(registryPath, JSON.stringify(registry));
+
+      const result = await api.editClassName({
+        action: "editClassName",
+        id: "test.tsx:15",
+        className: "img object-contain",
+        previousClassName: "img object-cover",
+      });
+
+      expect(result.success).toBe(true);
+      expect(await fs.readFile(sourcePath, "utf-8")).toBe(`<img className="img object-contain" />`);
+      // Registered under the preview's id so the next edit resolves directly.
+      expect(api.getRegistry()?.elements["test.tsx:15"]?.originalContent).toBe("img object-contain");
+    });
+
+    test("keeps failing on a stale id without previousClassName", async () => {
+      await fs.writeFile(path.join(tempDir, "test.tsx"), `<img className="img" />`);
+      const registry: EditableRegistry = { version: 1, generatedAt: new Date().toISOString(), elements: {} };
+      await fs.writeFile(registryPath, JSON.stringify(registry));
+
+      const result = await api.editClassName({ action: "editClassName", id: "test.tsx:15", className: "x" });
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("not found in registry");
+    });
+
     test("should fail if element is not className type", async () => {
       const registry: EditableRegistry = {
         version: 1,

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

@@ -1569,6 +1569,27 @@ describe("upstart-editor-vite-plugin", () => {
       expect(result).toContain('data-upstart-editable-text="true"');
     });
 
+    test("wraps a <Trans> in its own editable <span> when an icon sibling would be destroyed", () => {
+      const code = `
+        import { Trans } from "react-i18next";
+        import { Icon } from "@iconify/react";
+        export default function Badge() {
+          return <div className="badge"><Icon icon="lucide:sparkles" /><Trans i18nKey="nav.badge" /></div>;
+        }
+      `;
+      const result = transform(code) ?? "";
+      // The container keeps its hash but is not editable itself…
+      const container = result.match(/<div[^>]*className="badge"[^>]*>/)?.[0] ?? "";
+      expect(container).toContain("data-upstart-hash=");
+      expect(container).not.toContain("data-upstart-editable-text");
+      // …the <Trans> is wrapped in an editable span carrying the i18n attributes.
+      expect(result).toMatch(
+        /<span data-upstart-hash="[a-f0-9]+" data-upstart-editable-text="true" data-upstart-editable-text-mode="plain" data-upstart-i18n="translation:nav\.badge"><Trans i18nKey="nav\.badge" \/><\/span>/,
+      );
+      // The icon is untouched.
+      expect(result).toMatch(/<Icon [^>]*icon="lucide:sparkles"[^>]*\/>/);
+    });
+
     test("should promote <Trans> with custom namespace to parent", () => {
       const code = `
         import { Trans } from "react-i18next";

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/array-controls.ts

@@ -1,5 +1,6 @@
 import { getCurrentMode } from "./state.js";
 import { sendToParent } from "./utils.js";
+import { getLabels } from "./labels.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
@@ -7,7 +8,6 @@ import { sendToParent } from "./utils.js";
 // 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.
@@ -299,7 +299,7 @@ function makeItemDeleteButton(
 ): 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.title = marked ? getLabels().keepItem : getLabels().removeItem;
   btn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -316,7 +316,7 @@ function makeItemDeleteButton(
 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.title = getLabels().removeItem;
   btn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -329,7 +329,7 @@ function makeDraftRemoveButton(pill: HTMLElement, rect: DOMRect): HTMLButtonElem
 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.title = getLabels().addItem;
   btn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -341,7 +341,7 @@ function makeAddButton(arrayId: string, top: number, left: number): HTMLButtonEl
 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.title = getLabels().applyChanges;
   btn.addEventListener("click", (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -357,7 +357,7 @@ function makeDragHandle(arrayId: string, node: HTMLElement, rect: DOMRect): HTML
   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.title = getLabels().dragToReorder;
   btn.style.cursor = "grab";
   btn.addEventListener("pointerdown", (e) => {
     e.preventDefault();
@@ -430,7 +430,7 @@ function addDraftPill(arrayId: string): void {
   pill.removeAttribute("style");
   pill.setAttribute(DRAFT_ATTR, arrayId);
   pill.setAttribute("contenteditable", "true");
-  pill.textContent = DEFAULT_NEW_ITEM;
+  pill.textContent = getLabels().newItem;
 
   // Insert after the current last pill of this array (drafts go at the end).
   const last = draftPillsFor(arrayId).pop() ?? originalItemsFor(arrayId).pop();