@upstart.gg/vite-plugins 0.1.84 → 0.1.85

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

@@ -0,0 +1,220 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { UpstartEditorAPI, mapOffset, moveRange } from "../upstart-editor-api";
+import { transformWithOxc, getRegistry, clearRegistry } from "../vite-plugin-upstart-attrs";
+
+const FILE = "app/components/Hero.tsx";
+
+const HERO = `export function Hero() {
+  return (
+    <section className="hero">
+      <h1>Welcome</h1>
+      <p>Some text</p>
+      <div className="media">
+        <img src="/images/hero.webp" alt="" />
+        <span>Caption</span>
+      </div>
+    </section>
+  );
+}
+`;
+
+type Position = "before" | "after";
+
+describe("moveElements", () => {
+  let tempDir: string;
+  let api: UpstartEditorAPI;
+
+  // Run the attrs plugin on `code`, register it in the API and write the file; returns the
+  // movable element ids keyed by tag name.
+  async function setup(code: string): Promise<Record<string, string>> {
+    clearRegistry();
+    transformWithOxc(code, FILE);
+    const ids: Record<string, string> = {};
+    for (const [id, entry] of Object.entries(getRegistry())) {
+      if (entry.type !== "element") continue;
+      const tag = entry.originalContent.match(/^<([a-z0-9]+)/)?.[1];
+      if (tag) ids[tag] = id;
+    }
+    await fs.mkdir(path.join(tempDir, "app", "components"), { recursive: true });
+    await fs.writeFile(path.join(tempDir, FILE), code);
+    api.setRegistry({ version: 1, generatedAt: "", elements: getRegistry() });
+    return ids;
+  }
+
+  const read = () => fs.readFile(path.join(tempDir, FILE), "utf-8");
+  const move = (...moves: [id: string, targetId: string, position: Position][]) =>
+    api.moveElements({
+      action: "moveElements",
+      moves: moves.map(([id, targetId, position]) => ({ id, targetId, position })),
+    });
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "upstart-move-"));
+    api = new UpstartEditorAPI(tempDir, path.join(tempDir, "registry.json"));
+  });
+
+  afterEach(async () => {
+    clearRegistry();
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  test("moves an element after a sibling", async () => {
+    const ids = await setup(HERO);
+    const result = await move([ids.h1, ids.p, "after"]);
+    expect(result).toEqual({ success: true, filePaths: [path.join(tempDir, FILE)] });
+    expect(await read()).toBe(
+      HERO.replace("<h1>Welcome</h1>\n      <p>Some text</p>", "<p>Some text</p>\n      <h1>Welcome</h1>"),
+    );
+  });
+
+  test("moves an element before a sibling", async () => {
+    const ids = await setup(HERO);
+    expect((await move([ids.p, ids.h1, "before"])).success).toBe(true);
+    expect(await read()).toContain("<p>Some text</p>\n      <h1>Welcome</h1>");
+  });
+
+  test("re-indents an element moved to another nesting level", async () => {
+    const ids = await setup(HERO);
+    expect((await move([ids.img, ids.h1, "before"])).success).toBe(true);
+    const code = await read();
+    expect(code).toContain(
+      '<section className="hero">\n      <img src="/images/hero.webp" alt="" />\n      <h1>',
+    );
+    expect(code).toContain('<div className="media">\n        <span>Caption</span>\n      </div>');
+  });
+
+  test("applies several moves in order, tracking the elements an earlier move shifted", async () => {
+    const ids = await setup(HERO);
+    const result = await move(
+      [ids.img, ids.h1, "before"],
+      [ids.h1, ids.p, "after"],
+      [ids.img, ids.h1, "after"],
+    );
+    expect(result.success).toBe(true);
+    expect(await read()).toContain(
+      '<section className="hero">\n      <p>Some text</p>\n      <h1>Welcome</h1>\n      <img src="/images/hero.webp" alt="" />\n      <div className="media">',
+    );
+  });
+
+  test("a move undone by a later one leaves the file unchanged and reports no file", async () => {
+    const ids = await setup(HERO);
+    const result = await move([ids.h1, ids.p, "after"], [ids.h1, ids.p, "before"]);
+    expect(result).toEqual({ success: true, filePaths: [] });
+    expect(await read()).toBe(HERO);
+  });
+
+  test("moving an element next to itself leaves the file unchanged", async () => {
+    const ids = await setup(HERO);
+    expect(await move([ids.p, ids.h1, "after"])).toEqual({ success: true, filePaths: [] });
+    expect(await read()).toBe(HERO);
+  });
+
+  test("finds an element whose offsets shifted after an earlier edit", async () => {
+    const ids = await setup(HERO);
+    await fs.writeFile(path.join(tempDir, FILE), `// edited\n${HERO}`);
+    expect((await move([ids.h1, ids.p, "after"])).success).toBe(true);
+    expect(await read()).toContain("<p>Some text</p>\n      <h1>Welcome</h1>");
+  });
+
+  test("refuses elements from different files and writes nothing", async () => {
+    const ids = await setup(HERO);
+    const elements = getRegistry();
+    elements[ids.p] = { ...elements[ids.p], file: "app/components/Other.tsx" };
+    api.setRegistry({ version: 1, generatedAt: "", elements });
+    expect((await move([ids.h1, ids.img, "after"], [ids.h1, ids.p, "after"])).success).toBe(false);
+    expect(await read()).toBe(HERO);
+  });
+
+  test("refuses ids that are not movable elements", async () => {
+    const ids = await setup(HERO);
+    const classNameId = Object.entries(getRegistry()).find(([, e]) => e.type === "className")![0];
+    expect((await move([classNameId, ids.h1, "after"])).success).toBe(false);
+  });
+
+  test("refuses to move an element into itself", async () => {
+    const code = `export function A() {
+  return (
+    <div>
+      <p>
+        Hello <strong>world</strong>
+      </p>
+    </div>
+  );
+}
+`;
+    await fs.mkdir(path.join(tempDir, "app", "components"), { recursive: true });
+    await fs.writeFile(path.join(tempDir, FILE), code);
+    const outer = code.slice(code.indexOf("<p>"), code.indexOf("</p>") + 4);
+    api.setRegistry({
+      version: 1,
+      generatedAt: "",
+      elements: {
+        outer: {
+          file: FILE,
+          type: "element",
+          startOffset: code.indexOf("<p>"),
+          endOffset: code.indexOf("<p>") + outer.length,
+          originalContent: outer,
+          context: { parentTag: "div" },
+        },
+        inner: {
+          file: FILE,
+          type: "element",
+          startOffset: code.indexOf("<strong>"),
+          endOffset: code.indexOf("</strong>") + 9,
+          originalContent: "<strong>world</strong>",
+          context: { parentTag: "p" },
+        },
+      },
+    });
+    expect((await move(["outer", "inner", "after"])).success).toBe(false);
+    expect(await read()).toBe(code);
+  });
+});
+
+describe("moveRange", () => {
+  const range = (code: string, part: string) => {
+    const start = code.indexOf(part);
+    return { start, end: start + part.length };
+  };
+
+  test("moves inline elements as-is", () => {
+    const code = "<p><a>1</a> <b>2</b></p>";
+    const edit = moveRange(code, range(code, "<b>2</b>"), range(code, "<a>1</a>"), "before");
+    expect(edit.code).toBe("<p><b>2</b><a>1</a> </p>");
+    expect(edit.code.slice(edit.moved.start, edit.moved.end)).toBe("<b>2</b>");
+  });
+
+  test("moves an element after the last line of the file", () => {
+    const code = "  <a />\n  <b />";
+    const edit = moveRange(code, range(code, "<a />"), range(code, "<b />"), "after");
+    expect(edit.code).toBe("  <b />\n  <a />");
+    expect(edit.code.slice(edit.moved.start, edit.moved.end)).toBe("<a />");
+  });
+
+  test("moves a multi-line element and keeps its inner indentation", () => {
+    const code = "    <ul>\n      <li>x</li>\n    </ul>\n  <p>y</p>\n";
+    const edit = moveRange(
+      code,
+      range(code, "<ul>\n      <li>x</li>\n    </ul>"),
+      range(code, "<p>y</p>"),
+      "after",
+    );
+    expect(edit.code).toBe("  <p>y</p>\n  <ul>\n    <li>x</li>\n  </ul>\n");
+    expect(edit.code.slice(edit.moved.start, edit.moved.end)).toBe("<ul>\n    <li>x</li>\n  </ul>");
+  });
+
+  test("mapOffset follows the elements around the move", () => {
+    const code = "<a />\n<b />\n<c />\n<d />\n";
+    const edit = moveRange(code, range(code, "<a />"), range(code, "<c />"), "after");
+    expect(edit.code).toBe("<b />\n<c />\n<a />\n<d />\n");
+    for (const tag of ["<b />", "<c />", "<d />"]) {
+      const r = range(code, tag);
+      const start = mapOffset(edit, r.start, false);
+      expect(edit.code.slice(start, mapOffset(edit, r.end, true))).toBe(tag);
+    }
+  });
+});

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

@@ -1581,10 +1581,10 @@ describe("upstart-editor-vite-plugin", () => {
       const registry = getRegistry();
       const entries = Object.values(registry);
 
-      // 2 text (spans) + 2 className (spans); the outer div is NOT almost-leaf because
-      // its <span> children have attributes (className), which disqualifies them as
-      // simple inline formatting wrappers.
-      expect(entries.length).toBe(4);
+      // 2 text (spans) + 2 className (spans) + 2 movable elements (spans); the outer div is
+      // NOT almost-leaf because its <span> children have attributes (className), which
+      // disqualifies them as simple inline formatting wrappers.
+      expect(entries.length).toBe(6);
 
       const textEntries = entries.filter((e) => e.type === "text");
       const classEntries = entries.filter((e) => e.type === "className");
@@ -1596,6 +1596,167 @@ describe("upstart-editor-vite-plugin", () => {
     });
   });
 
+  describe("Movable elements (drag & drop)", () => {
+    const moveIdOf = (out: string, text: string) =>
+      out.match(new RegExp(`data-upstart-move-id="([^"]+)"[^>]*>${text}<`))?.[1];
+
+    test("marks text and image elements that are direct JSX children", () => {
+      const code = `export function Hero() {
+  return (
+    <section>
+      <h1>Title</h1>
+      <p>Body</p>
+      <img src="/a.webp" alt="" />
+    </section>
+  );
+}`;
+      const out = transform(code)!;
+      expect(out.match(/data-upstart-move-id=/g)?.length).toBe(3);
+      // The <section> root is not a text/image element and has no JSX parent.
+      expect(out).not.toMatch(/<section[^>]*data-upstart-move-id/);
+      const id = moveIdOf(out, "Title")!;
+      const entry = getRegistry()[id];
+      expect(entry.type).toBe("element");
+      expect(entry.originalContent).toBe("<h1>Title</h1>");
+      expect(code.slice(entry.startOffset, entry.endOffset)).toBe("<h1>Title</h1>");
+    });
+
+    test("does not mark elements in loops, conditionals or components", () => {
+      const code = `export function List({ show }) {
+  return (
+    <div>
+      {["a", "b"].map((x, i) => <span key={i}>{x}</span>)}
+      {show && <p>Maybe</p>}
+      {show ? <h2>Yes</h2> : <h2>No</h2>}
+      <Title>Component</Title>
+    </div>
+  );
+}`;
+      const out = transform(code)!;
+      expect(out).not.toContain("data-upstart-move-id");
+    });
+
+    test("marks whole blocks, not only texts and images", () => {
+      const code = `export function Page() {
+  return (
+    <main>
+      <section className="a">
+        <div className="card">
+          <h2>Title</h2>
+          <p>Text</p>
+        </div>
+        <a href="/more">More</a>
+      </section>
+      <ul>
+        <li>One</li>
+        <li>Two</li>
+      </ul>
+    </main>
+  );
+}`;
+      const out = transform(code)!;
+      for (const tag of ["section", "div", "h2", "ul", "li"]) {
+        expect(out).toMatch(new RegExp(`<${tag}[^>]*data-upstart-move-id=`));
+      }
+      expect(out).not.toMatch(/<main[^>]*data-upstart-move-id/);
+      const sectionId = out.match(/<section[^>]*data-upstart-move-id="([^"]+)"/)![1];
+      expect(getRegistry()[sectionId].originalContent).toMatch(/^<section className="a">[\s\S]*<\/section>$/);
+    });
+
+    test("does not mark the only content of an HTML element: its parent moves instead", () => {
+      const code = `export function Page() {
+  return (
+    <main>
+      <section className="outer">
+        <div className="wrapper">
+          <div className="container">
+            <h2>Title</h2>
+            <p>Body</p>
+          </div>
+        </div>
+      </section>
+      <figure>
+        {/* comment */}
+        <img src="/a.webp" alt="" />
+      </figure>
+      <p>
+        Hello <strong>you</strong>
+      </p>
+      <p>{name}<em>!</em></p>
+      <Card>
+        <h3>Inside a component</h3>
+      </Card>
+    </main>
+  );
+}`;
+      const out = transform(code)!;
+      const movable = (tag: string) => new RegExp(`<${tag}[ >][^>]*data-upstart-move-id=`);
+      // section > wrapper > container: only the section carries a handle for the chain.
+      expect(out).toMatch(movable("section"));
+      expect(out).not.toMatch(/className="wrapper"[^>]*data-upstart-move-id/);
+      expect(out).not.toMatch(/className="container"[^>]*data-upstart-move-id/);
+      // Siblings are not "only content".
+      expect(out).toMatch(movable("h2"));
+      expect(out).toMatch(movable("p"));
+      // A comment does not count as content: the <img> is the figure's only content.
+      expect(out).toMatch(movable("figure"));
+      expect(out).not.toMatch(movable("img"));
+      // Text or an expression next to the element keeps it movable.
+      expect(out).toMatch(movable("strong"));
+      expect(out).toMatch(movable("em"));
+      // The child of a component stays movable.
+      expect(out).toMatch(movable("h3"));
+    });
+
+    test("does not mark document structure, SVG internals, Trans slots or <br>", () => {
+      const code = `export function Layout() {
+  return (
+    <html>
+      <head>
+        <meta charSet="utf-8" />
+        <title>Site</title>
+      </head>
+      <body>
+        <p>
+          Hello<br />world
+        </p>
+        <svg viewBox="0 0 10 10">
+          <path d="M0 0" />
+        </svg>
+        <span>
+          <Trans i18nKey="x" components={{ b: <b /> }}>
+            <b>bold</b>
+          </Trans>
+        </span>
+      </body>
+    </html>
+  );
+}`;
+      const out = transform(code)!;
+      for (const tag of ["html", "head", "meta", "title", "body", "br", "path", "b"]) {
+        expect(out).not.toMatch(new RegExp(`<${tag}[ /][^>]*data-upstart-move-id=`));
+      }
+      // The <p>, the <svg> itself and the <span> stay movable.
+      for (const tag of ["p", "svg", "span"]) {
+        expect(out).toMatch(new RegExp(`<${tag}[^>]*data-upstart-move-id=`));
+      }
+    });
+
+    test("gives each component of a file its own scope", () => {
+      const code = `export function A() {
+  return <div><p>One</p><p>Uno</p></div>;
+}
+export function B() {
+  return <div><p>Two</p><p>Dos</p></div>;
+}`;
+      const out = transform(code)!;
+      const scopes = [...new Set([...out.matchAll(/data-upstart-move-scope="([^"]+)"/g)].map((m) => m[1]))];
+      expect(scopes).toHaveLength(2);
+      // Scope = start offset of the enclosing function (after "export ").
+      expect(scopes[0]).toBe("test.tsx:7");
+    });
+  });
+
   describe("Integration Tests", () => {
     test("should transform real-world component correctly", () => {
       const code = `

package/src/upstart-editor-api.ts

@@ -341,6 +341,150 @@ function printMetaTag(fieldName: string, value: string): string {
   return `<meta name="${fieldName}" ${attribute} />`;
 }
 
+interface SourceRange {
+  start: number;
+  end: number;
+}
+
+/** A tracked element: its current range and the source it is expected to hold there. */
+interface TrackedElement extends SourceRange {
+  content: string;
+}
+
+/**
+ * Current range of an element in `code`: `hint` when the source still matches there, otherwise
+ * the occurrence of its source nearest to `hint` (an earlier edit shifted it), and as a last
+ * resort a whitespace-insensitive match (a move re-indented it).
+ */
+function locateElement(code: string, hint: TrackedElement): TrackedElement | null {
+  const { start, end, content } = hint;
+  if (code.slice(start, end) === content) return hint;
+  if (content.trim() === "") return null;
+  const nearest = (a: number, b: number) => Math.abs(a - start) < Math.abs(b - start);
+  let best = -1;
+  for (let i = code.indexOf(content); i !== -1; i = code.indexOf(content, i + 1)) {
+    if (best === -1 || nearest(i, best)) best = i;
+  }
+  if (best !== -1) return { start: best, end: best + content.length, content };
+
+  const pattern = content
+    .trim()
+    .split(/\s+/)
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("\\s+");
+  let found: TrackedElement | null = null;
+  for (const m of code.matchAll(new RegExp(pattern, "g"))) {
+    if (!found || nearest(m.index, found.start)) {
+      found = { start: m.index, end: m.index + m[0].length, content: m[0] };
+    }
+  }
+  return found;
+}
+
+/**
+ * The full lines a range occupies (from the line start to just after its trailing newline)
+ * when nothing else than whitespace shares those lines, plus the indentation of the first one.
+ */
+function ownLines(code: string, range: SourceRange): { start: number; end: number; indent: string } | null {
+  const lineStart = code.lastIndexOf("\n", range.start - 1) + 1;
+  const indent = code.slice(lineStart, range.start);
+  if (indent.trim() !== "") return null;
+  const newline = code.indexOf("\n", range.end);
+  const lineEnd = newline === -1 ? code.length : newline;
+  if (code.slice(range.end, lineEnd).trim() !== "") return null;
+  return { start: lineStart, end: newline === -1 ? code.length : newline + 1, indent };
+}
+
+/**
+ * The result of moving a range: the new code, plus what changed so the offsets of other
+ * elements can be mapped onto it (see `mapOffset`). Offsets are in the ORIGINAL code, except
+ * `moved`, which is the new range of the moved element.
+ */
+export interface MoveEdit {
+  code: string;
+  /** Removed source range. */
+  removeStart: number;
+  removeEnd: number;
+  /** Where the moved text was inserted, and its length. */
+  insertAt: number;
+  insertLength: number;
+  moved: SourceRange;
+}
+
+/**
+ * Move the `src` range before or after the `tgt` range (`tgt` must not be inside `src`).
+ * Elements alone on their lines are moved as whole lines, re-indented to the target's level;
+ * inline elements are moved as-is. Inserting at the far edge of the target keeps the target's
+ * own range untouched even when the source sits inside it (e.g. a <span> out of its <p>).
+ */
+export function moveRange(
+  code: string,
+  src: SourceRange,
+  tgt: SourceRange,
+  position: "before" | "after",
+): MoveEdit {
+  const srcLines = ownLines(code, src);
+  const tgtLines = ownLines(code, tgt);
+  let removeStart = src.start;
+  let removeEnd = src.end;
+  let insertAt = position === "before" ? tgt.start : tgt.end;
+  let inserted = code.slice(src.start, src.end);
+  let elementOffset = 0;
+  let elementLength = inserted.length;
+
+  if (srcLines && tgtLines) {
+    // Re-indent every line of the element from its own indentation to the target's.
+    const body = inserted
+      .split("\n")
+      .map((line, i) => {
+        if (i === 0) return line;
+        return line.startsWith(srcLines.indent) ? tgtLines.indent + line.slice(srcLines.indent.length) : line;
+      })
+      .join("\n");
+    removeStart = srcLines.start;
+    removeEnd = srcLines.end;
+    elementOffset = tgtLines.indent.length;
+    elementLength = body.length;
+    if (position === "before") {
+      insertAt = tgtLines.start;
+      inserted = `${tgtLines.indent}${body}\n`;
+    } else {
+      insertAt = tgtLines.end;
+      const atEofWithoutNewline = tgtLines.end === code.length && !code.endsWith("\n");
+      inserted = atEofWithoutNewline ? `\n${tgtLines.indent}${body}` : `${tgtLines.indent}${body}\n`;
+      if (atEofWithoutNewline) elementOffset += 1;
+    }
+  }
+
+  const removed = removeEnd - removeStart;
+  const next =
+    insertAt <= removeStart
+      ? code.slice(0, insertAt) + inserted + code.slice(insertAt, removeStart) + code.slice(removeEnd)
+      : code.slice(0, removeStart) + code.slice(removeEnd, insertAt) + inserted + code.slice(insertAt);
+  const insertedAtInNewCode = insertAt <= removeStart ? insertAt : insertAt - removed;
+  const movedStart = insertedAtInNewCode + elementOffset;
+  return {
+    code: next,
+    removeStart,
+    removeEnd,
+    insertAt,
+    insertLength: inserted.length,
+    moved: { start: movedStart, end: movedStart + elementLength },
+  };
+}
+
+/**
+ * Where an offset of the original code (outside the removed range) lands after `edit`.
+ * A start sitting exactly at the insertion point is pushed after the inserted text, an end
+ * sitting there stays before it.
+ */
+export function mapOffset(edit: MoveEdit, offset: number, isEnd: boolean): number {
+  let mapped = offset;
+  if (offset >= edit.removeEnd) mapped -= edit.removeEnd - edit.removeStart;
+  if (isEnd ? offset > edit.insertAt : offset >= edit.insertAt) mapped += edit.insertLength;
+  return mapped;
+}
+
 /** Start of the line `offset` sits on, so a removed tag doesn't leave a blank line behind. */
 function lineRangeStart(code: string, offset: number): number {
   const lineStart = code.lastIndexOf("\n", offset);
@@ -422,6 +566,27 @@ export const payloadArraySet = z.object({
 
 export type PayloadArraySet = z.infer<typeof payloadArraySet>;
 
+// Move JSX elements (registry entries of type "element") before or after other elements of the
+// same file — the editor's drag & drop. Moves are staged in the preview and applied together,
+// in order, when the user confirms. Ids are "<relativeFile>:<elementStart>".
+export const payloadMoveElements = z.object({
+  action: z.literal("moveElements"),
+  moves: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        targetId: z.string().min(1),
+        position: z.enum(["before", "after"]),
+      }),
+    )
+    .min(1)
+    .max(200),
+});
+
+export type PayloadMoveElements = z.infer<typeof payloadMoveElements>;
+
+export type MoveElementsResult = { success: true; filePaths: string[] } | { success: false; error: string };
+
 // React-router route id, as reported by the client runtime (e.g. "routes/_layout._index",
 // "root"). Resolved to `<projectRoot>/app/<routeId>.<ext>` — see `resolveRouteFile`.
 const routeIdSchema = z
@@ -938,6 +1103,104 @@ export class UpstartEditorAPI {
     }
   }
 
+  /**
+   * Apply a batch of element moves (editor drag & drop), in order. Every element involved is
+   * tracked across the moves, so a later move finds elements an earlier one shifted. Files are
+   * only written when every move succeeded and every result still parses.
+   */
+  async moveElements(params: PayloadMoveElements): Promise<MoveElementsResult> {
+    const parsed = payloadMoveElements.safeParse(params);
+    if (!parsed.success) {
+      return { success: false, error: `Invalid payload: ${parsed.error.message}` };
+    }
+    if (!this.registry) {
+      try {
+        await this.loadRegistry();
+      } catch (err) {
+        return { success: false, error: `Failed to load registry: ${err}` };
+      }
+    }
+    const elements = this.registry!.elements;
+
+    const codes = new Map<string, string>();
+    const tracked = new Map<string, TrackedElement>();
+    try {
+      for (const { id, targetId, position } of parsed.data.moves) {
+        if (id === targetId) return { success: false, error: "Cannot move an element onto itself" };
+        const source = elements[id];
+        const target = elements[targetId];
+        if (source?.type !== "element")
+          return { success: false, error: `Element ${id} not found in registry` };
+        if (target?.type !== "element") {
+          return { success: false, error: `Element ${targetId} not found in registry` };
+        }
+        if (source.file !== target.file) {
+          return { success: false, error: "Elements can only be moved within the same file" };
+        }
+
+        const file = source.file;
+        let code = codes.get(file);
+        if (code === undefined) {
+          code = await fs.readFile(path.join(this.projectRoot, file), "utf-8");
+          codes.set(file, code);
+          // Track every movable element of the file: any of them may be shifted by a move.
+          for (const [elementId, entry] of Object.entries(elements)) {
+            if (entry.type !== "element" || entry.file !== file) continue;
+            tracked.set(elementId, {
+              start: entry.startOffset,
+              end: entry.endOffset,
+              content: entry.originalContent,
+            });
+          }
+        }
+
+        const src = locateElement(code, tracked.get(id)!);
+        const tgt = locateElement(code, tracked.get(targetId)!);
+        if (!src || !tgt) {
+          return { success: false, error: `Element not found in ${file}. The file may have been modified.` };
+        }
+        if (tgt.start >= src.start && tgt.end <= src.end) {
+          return { success: false, error: "Cannot move an element inside itself" };
+        }
+
+        const edit = moveRange(code, src, tgt, position);
+        codes.set(file, edit.code);
+        for (const [elementId, el] of tracked) {
+          if (elementId === id) continue;
+          if (elements[elementId].file !== file) continue;
+          if (el.start >= src.start && el.end <= src.end) {
+            // Inside the moved element: shifted along with it (re-indentation is caught up
+            // by the whitespace-insensitive lookup of locateElement).
+            const delta = edit.moved.start - src.start;
+            tracked.set(elementId, { ...el, start: el.start + delta, end: el.end + delta });
+          } else {
+            tracked.set(elementId, {
+              ...el,
+              start: mapOffset(edit, el.start, false),
+              end: mapOffset(edit, el.end, true),
+            });
+          }
+        }
+        tracked.set(id, { ...edit.moved, content: edit.code.slice(edit.moved.start, edit.moved.end) });
+      }
+
+      const changed: [filePath: string, code: string][] = [];
+      for (const [file, code] of codes) {
+        const filePath = path.join(this.projectRoot, file);
+        if (code === (await fs.readFile(filePath, "utf-8"))) continue;
+        if (parseSync(file, code, { sourceType: "module" }).errors.length > 0) {
+          return { success: false, error: `Moving the elements would produce invalid code in ${file}` };
+        }
+        changed.push([filePath, code]);
+      }
+      for (const [filePath, code] of changed) await fs.writeFile(filePath, code);
+      if (changed.length > 0) this.registry = null;
+      return { success: true, filePaths: changed.map(([filePath]) => filePath) };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  }
+
   /**
    * Read the page metadata shown in the browser tab and in search results.
    *