@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/slides-2/server/lib/slide-source-editing/edit-ops.ts

@@ -0,0 +1,1478 @@
+import * as t from "@babel/types";
+
+import {
+  findJsxAncestors,
+  parseSource,
+  walkAll,
+  walkJsx,
+} from "./babel-walk.js";
+import { textDiff } from "./text-diff.js";
+
+export type EditOp =
+  | { kind: "set-style"; key: string; value: string | null; prevText?: string }
+  | { kind: "set-text"; value: string; prevText?: string }
+  | {
+      kind: "set-text-range-style";
+      start: number;
+      end: number;
+      key: string;
+      value: string | null;
+      prevText?: string;
+    }
+  | { kind: "set-attr-asset"; attr: string; assetId: string }
+  | { kind: "replace-placeholder-with-image"; assetId: string }
+  | { kind: "insert-image-asset"; assetId: string; alt: string };
+
+export type ApplyEditResult =
+  | { ok: true; source: string }
+  | { ok: false; status: number; error: string };
+
+export type Splice = { from: number; to: number; text: string };
+
+export function jsString(s: string): string {
+  return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n")}'`;
+}
+
+export function spliceRange(node: t.Node, text: string): Splice {
+  return { from: node.start ?? 0, to: node.end ?? 0, text };
+}
+
+// Splices are applied back-to-front so earlier offsets stay valid, then the
+// result is re-parsed — a rewrite that cannot be parsed is rejected whole.
+export function applySplices(
+  source: string,
+  splices: Splice[],
+): ApplyEditResult {
+  const ordered = [...splices].sort((a, b) => b.from - a.from);
+  let next = source;
+  for (const sp of ordered) {
+    next = next.slice(0, sp.from) + sp.text + next.slice(sp.to);
+  }
+  if (!parseSource(next)) {
+    return {
+      ok: false,
+      status: 422,
+      error: "edit would produce invalid source",
+    };
+  }
+  return { ok: true, source: next };
+}
+
+// Emit a JSX attribute value: `"foo"` when the value is round-trip-safe
+// inside double quotes; otherwise wrap in `{...}` so escapes work.
+export function formatJsxAttrValue(value: string): string {
+  if (/^[^"\\<>&{}\n\r]*$/.test(value)) return `"${value}"`;
+  return `{${jsString(value)}}`;
+}
+
+function jsxAttrName(attr: t.JSXAttribute): string | null {
+  return t.isJSXIdentifier(attr.name) ? attr.name.name : null;
+}
+
+export function findJsxAttr(
+  opening: t.JSXOpeningElement,
+  name: string,
+): t.JSXAttribute | null {
+  for (const attr of opening.attributes) {
+    if (t.isJSXAttribute(attr) && jsxAttrName(attr) === name) return attr;
+  }
+  return null;
+}
+
+export function readJsxStringAttr(
+  opening: t.JSXOpeningElement,
+  name: string,
+): string | null {
+  const attr = findJsxAttr(opening, name);
+  const v = attr?.value;
+  if (!v) return null;
+  if (t.isStringLiteral(v)) return v.value;
+  if (t.isJSXExpressionContainer(v) && t.isStringLiteral(v.expression))
+    return v.expression.value;
+  return null;
+}
+
+function readJsxNumberAttr(
+  opening: t.JSXOpeningElement,
+  name: string,
+): number | null {
+  const attr = findJsxAttr(opening, name);
+  const v = attr?.value;
+  if (!v || !t.isJSXExpressionContainer(v)) return null;
+  if (!t.isNumericLiteral(v.expression)) return null;
+  const n = v.expression.value;
+  return Number.isFinite(n) ? n : null;
+}
+
+export type ImportInfo = {
+  node: t.ImportDeclaration;
+  source: string;
+  defaultIdent: string | null;
+};
+
+export function findImports(ast: t.File): ImportInfo[] {
+  const out: ImportInfo[] = [];
+  for (const node of ast.program.body) {
+    if (!t.isImportDeclaration(node)) continue;
+    let def: string | null = null;
+    for (const spec of node.specifiers) {
+      if (t.isImportDefaultSpecifier(spec)) {
+        def = spec.local.name;
+        break;
+      }
+    }
+    out.push({ node, source: node.source.value, defaultIdent: def });
+  }
+  return out;
+}
+
+export function safeAssetIdentifier(
+  filename: string,
+  taken: Set<string>,
+): string {
+  const stem = filename.replace(/\.[^.]+$/, "");
+  let camel = "";
+  let upper = false;
+  for (const ch of stem) {
+    if (/[A-Za-z0-9]/.test(ch)) {
+      camel += upper ? ch.toUpperCase() : ch;
+      upper = false;
+    } else {
+      upper = camel.length > 0;
+    }
+  }
+  let base = camel;
+  if (!base || !/^[A-Za-z_$]/.test(base)) {
+    base = `asset${base.charAt(0).toUpperCase()}${base.slice(1)}` || "asset";
+  }
+  base = base.charAt(0).toLowerCase() + base.slice(1);
+  let candidate = base;
+  let i = 2;
+  while (taken.has(candidate)) {
+    candidate = `${base}${i}`;
+    i += 1;
+  }
+  return candidate;
+}
+
+function findJsxByStart(
+  ast: t.Node,
+  line: number,
+  column: number,
+): t.JSXElement | null {
+  let hit: t.JSXElement | null = null;
+  walkJsx(ast, (n) => {
+    if (!t.isJSXElement(n) || !n.loc) return;
+    const s = n.loc.start;
+    if (s.line === line && s.column === column) {
+      hit = n;
+      return "stop";
+    }
+  });
+  return hit;
+}
+
+function findInnermostJsxElement(
+  ast: t.Node,
+  line: number,
+  column: number,
+): t.JSXElement | null {
+  // Prefer exact `loc.start` match (what `data-slide-loc` sends) so
+  // we don't accidentally hit an outer JSX whose range happens to
+  // enclose the click point.
+  const exact = findJsxByStart(ast, line, column);
+  if (exact) return exact;
+
+  // Fallback for fiber-walked clicks whose column may not align with
+  // the opening `<`.
+  for (const n of findJsxAncestors(ast, line, column)) {
+    if (t.isJSXElement(n)) return n;
+  }
+  return null;
+}
+
+function findUniqueElementByText(
+  ast: t.Node,
+  prevText: string,
+): t.JSXElement | null {
+  const hits: Array<{ node: t.JSXElement; size: number }> = [];
+  walkJsx(ast, (n) => {
+    if (!t.isJSXElement(n)) return;
+    if (textRangeContent(collectTextRangeParts(n)) !== prevText) return;
+    hits.push({ node: n, size: (n.end ?? 0) - (n.start ?? 0) });
+  });
+  if (hits.length === 0) return null;
+  hits.sort((a, b) => a.size - b.size);
+  const best = hits[0];
+  const bestStart = best.node.start ?? 0;
+  const bestEnd = best.node.end ?? 0;
+  const hasSiblingMatch = hits
+    .slice(1)
+    .some(
+      ({ node }) => (node.start ?? 0) > bestStart || (node.end ?? 0) < bestEnd,
+    );
+  return hasSiblingMatch ? null : best.node;
+}
+
+function fallbackTextForOps(ops: EditOp[]): string | null {
+  for (const op of ops) {
+    if (
+      (op.kind === "set-style" ||
+        op.kind === "set-text" ||
+        op.kind === "set-text-range-style") &&
+      op.prevText !== undefined
+    ) {
+      return op.prevText;
+    }
+  }
+  return null;
+}
+
+function hasOnlyTextOps(ops: EditOp[]): boolean {
+  return ops.length > 0 && ops.every((op) => op.kind === "set-text");
+}
+
+function elementTextMatches(element: t.JSXElement, prevText: string): boolean {
+  return textRangeContent(collectTextRangeParts(element)) === prevText;
+}
+
+export function findElementForEdit(
+  ast: t.File,
+  line: number,
+  column: number,
+  ops: EditOp[],
+): t.JSXElement | null {
+  const element = findInnermostJsxElement(ast, line, column);
+  const prevText = fallbackTextForOps(ops);
+  if (prevText === null) return element;
+  if (
+    hasOnlyTextOps(ops) &&
+    element &&
+    (elementTextMatches(element, prevText) ||
+      elementTextCandidateMatches(ast, element, prevText))
+  ) {
+    return element;
+  }
+  return findUniqueElementByText(ast, prevText) ?? element;
+}
+
+function buildStyleSplice(
+  source: string,
+  element: t.JSXElement,
+  ops: Array<{ key: string; value: string | null }>,
+): Splice | { error: string } | null {
+  const opening = element.openingElement;
+  const existing = findJsxAttr(opening, "style");
+  type StyleEntry =
+    | { kind: "prop"; key: string; keyText: string; valueText: string }
+    | { kind: "raw"; text: string };
+  const entries: StyleEntry[] = [];
+  let hasRawEntry = false;
+
+  if (existing) {
+    const value = existing.value;
+    if (!value || !t.isJSXExpressionContainer(value)) {
+      return { error: "style attribute has unsupported form" };
+    }
+    const expr = value.expression;
+    if (!t.isObjectExpression(expr)) {
+      if (typeof expr.start !== "number" || typeof expr.end !== "number") {
+        return { error: "style value missing source range" };
+      }
+      entries.push({
+        kind: "raw",
+        text: `...(${source.slice(expr.start, expr.end)})`,
+      });
+      hasRawEntry = true;
+    } else {
+      for (const prop of expr.properties) {
+        if (t.isObjectProperty(prop) && !prop.computed) {
+          let keyName: string | null = null;
+          if (t.isIdentifier(prop.key)) keyName = prop.key.name;
+          else if (t.isStringLiteral(prop.key)) keyName = prop.key.value;
+          if (!keyName) return { error: "style has unsupported key" };
+          const v = prop.value;
+          if (
+            typeof prop.key.start !== "number" ||
+            typeof prop.key.end !== "number" ||
+            typeof v.start !== "number" ||
+            typeof v.end !== "number"
+          ) {
+            return { error: "style value missing source range" };
+          }
+          entries.push({
+            kind: "prop",
+            key: keyName,
+            keyText: source.slice(prop.key.start, prop.key.end),
+            valueText: source.slice(v.start, v.end),
+          });
+        } else {
+          if (typeof prop.start !== "number" || typeof prop.end !== "number") {
+            return { error: "style value missing source range" };
+          }
+          entries.push({
+            kind: "raw",
+            text: source.slice(prop.start, prop.end),
+          });
+          hasRawEntry = true;
+        }
+      }
+    }
+  }
+
+  for (const op of ops) {
+    const matching = entries.filter(
+      (entry): entry is Extract<StyleEntry, { kind: "prop" }> =>
+        entry.kind === "prop" && entry.key === op.key,
+    );
+    if (op.value === null) {
+      for (const entry of matching) entries.splice(entries.indexOf(entry), 1);
+      if (hasRawEntry) {
+        entries.push({
+          kind: "prop",
+          key: op.key,
+          keyText: op.key,
+          valueText: "undefined",
+        });
+      }
+    } else if (matching.length > 0) {
+      matching[matching.length - 1].valueText = jsString(op.value);
+    } else {
+      entries.push({
+        kind: "prop",
+        key: op.key,
+        keyText: op.key,
+        valueText: jsString(op.value),
+      });
+    }
+  }
+
+  if (entries.length === 0) {
+    if (!existing) return null;
+    let from = existing.start ?? 0;
+    if (from > 0 && source[from - 1] === " ") from -= 1;
+    return { from, to: existing.end ?? 0, text: "" };
+  }
+
+  const propsText = entries
+    .map((entry) =>
+      entry.kind === "prop"
+        ? `${entry.keyText}: ${entry.valueText}`
+        : entry.text,
+    )
+    .join(", ");
+  const newAttr = `style={{ ${propsText} }}`;
+
+  if (existing) {
+    const lastAttr = opening.attributes[opening.attributes.length - 1];
+    if (lastAttr && lastAttr !== existing && typeof lastAttr.end === "number") {
+      const attrsAfterStyle = source
+        .slice(existing.end ?? 0, lastAttr.end)
+        .replace(/^[ \t]+/, "");
+      return {
+        from: existing.start ?? 0,
+        to: lastAttr.end,
+        text: `${attrsAfterStyle} ${newAttr}`,
+      };
+    }
+    return { from: existing.start ?? 0, to: existing.end ?? 0, text: newAttr };
+  }
+  const lastAttr = opening.attributes[opening.attributes.length - 1];
+  const at = lastAttr?.end ?? opening.name.end ?? 0;
+  return { from: at, to: at, text: ` ${newAttr}` };
+}
+
+function formatJsxText(value: string): string {
+  // JSXText can't hold `{}<>` and collapses leading/trailing whitespace,
+  // so wrap the value in an expression container when it would lose info.
+  if (/[{}<>]/.test(value) || /^\s|\s$/.test(value) || value === "") {
+    return `{${jsString(value)}}`;
+  }
+  return value;
+}
+
+type TextCandidate = {
+  // Normalized current text the candidate represents — what an
+  // unambiguous DOM `textContent` would render here. Used to match
+  // against the client-supplied `prevText` when there's more than one.
+  current: string;
+  splice: (value: string) => Splice;
+};
+
+type JsxParent = t.JSXElement | t.JSXFragment;
+type TextRangeLeaf = {
+  node: t.JSXText | t.JSXExpressionContainer;
+  parent: JsxParent;
+  current: string;
+  raw: string;
+  text: (value: string) => string;
+  offsets: Array<number | null>;
+};
+type TextRangeBreak = { node: t.JSXElement; current: "\n" };
+type TextRangePart = TextRangeLeaf | TextRangeBreak;
+
+function meaningfulChildren(parent: JsxParent): t.Node[] {
+  return parent.children.filter((c) => {
+    if (t.isJSXText(c)) return c.value.trim() !== "";
+    return true;
+  });
+}
+
+function isOnlyMeaningfulChild(parent: JsxParent, child: t.Node): boolean {
+  const meaningful = meaningfulChildren(parent);
+  return meaningful.length === 1 && meaningful[0] === child;
+}
+
+// Wrap-style splice: rewrite the whole children span of `parent`. Used
+// when the candidate is the parent's only meaningful child, so old
+// surrounding whitespace nodes don't leak into the new value.
+function wrapSplice(parent: JsxParent, text: string): Splice {
+  const first = parent.children[0];
+  const last = parent.children[parent.children.length - 1];
+  return { from: first.start ?? 0, to: last.end ?? 0, text };
+}
+
+function splitLinesWithOffsets(
+  value: string,
+): Array<{ text: string; start: number }> {
+  const lines: Array<{ text: string; start: number }> = [];
+  let start = 0;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (ch !== "\n" && ch !== "\r") continue;
+    lines.push({ text: value.slice(start, i), start });
+    if (ch === "\r" && value[i + 1] === "\n") i += 1;
+    start = i + 1;
+  }
+  lines.push({ text: value.slice(start), start });
+  return lines;
+}
+
+function cleanJsxTextWithOffsets(value: string): {
+  text: string;
+  offsets: Array<number | null>;
+} {
+  const lines = splitLinesWithOffsets(value);
+  let lastNonEmptyLine = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].text.trim()) lastNonEmptyLine = i;
+  }
+
+  let text = "";
+  const offsets: Array<number | null> = [];
+  for (let i = 0; i < lines.length; i++) {
+    const chars = Array.from(lines[i].text, (ch, j) => ({
+      ch: ch === "\t" ? " " : ch,
+      offset: lines[i].start + j,
+    }));
+    let from = 0;
+    let to = chars.length;
+    if (i !== 0) {
+      while (from < to && chars[from].ch === " ") from += 1;
+    }
+    if (i !== lines.length - 1) {
+      while (to > from && chars[to - 1].ch === " ") to -= 1;
+    }
+    if (from >= to) continue;
+    for (const item of chars.slice(from, to)) {
+      text += item.ch;
+      offsets.push(item.offset);
+    }
+    if (i !== lastNonEmptyLine) {
+      text += " ";
+      offsets.push(null);
+    }
+  }
+  return { text, offsets };
+}
+
+function isJsxBrElement(node: t.Node): node is t.JSXElement {
+  if (!t.isJSXElement(node)) return false;
+  const name = node.openingElement.name;
+  return t.isJSXIdentifier(name) && name.name.toLowerCase() === "br";
+}
+
+function collectTextCandidates(element: JsxParent, out: TextCandidate[]): void {
+  const meaningful = meaningfulChildren(element);
+  const isSole = meaningful.length === 1;
+  for (const child of meaningful) {
+    if (t.isJSXText(child)) {
+      const current = child.value.trim();
+      if (!current) continue;
+      out.push({
+        current,
+        splice: (v) =>
+          isSole
+            ? wrapSplice(element, formatJsxText(v))
+            : {
+                from: child.start ?? 0,
+                to: child.end ?? 0,
+                text: formatJsxText(v),
+              },
+      });
+    } else if (t.isJSXExpressionContainer(child)) {
+      const expr = child.expression;
+      if (t.isStringLiteral(expr) || t.isNumericLiteral(expr)) {
+        const current = String(expr.value);
+        out.push({
+          current,
+          splice: (v) =>
+            isSole
+              ? wrapSplice(element, `{${jsString(v)}}`)
+              : {
+                  from: child.start ?? 0,
+                  to: child.end ?? 0,
+                  text: `{${jsString(v)}}`,
+                },
+        });
+      }
+    } else if (t.isJSXElement(child) || t.isJSXFragment(child)) {
+      collectTextCandidates(child, out);
+    }
+  }
+}
+
+function collectTextRangeParts(element: JsxParent): TextRangePart[] {
+  const parts: TextRangePart[] = [];
+  collectTextRangePartsRaw(element, parts);
+  return normalizeTextRangeParts(parts);
+}
+
+function collectTextRangePartsRaw(
+  element: JsxParent,
+  out: TextRangePart[],
+): void {
+  for (const child of element.children) {
+    if (t.isJSXText(child)) {
+      const { text: current, offsets } = cleanJsxTextWithOffsets(child.value);
+      if (current) {
+        out.push({
+          node: child,
+          parent: element,
+          current,
+          raw: child.value,
+          text: formatJsxText,
+          offsets,
+        });
+      }
+    } else if (t.isJSXExpressionContainer(child)) {
+      const expression = child.expression;
+      if (t.isStringLiteral(expression) || t.isNumericLiteral(expression)) {
+        const raw = String(expression.value);
+        const current = raw;
+        if (current) {
+          out.push({
+            node: child,
+            parent: element,
+            current,
+            raw,
+            text: (value) => `{${jsString(value)}}`,
+            offsets: Array.from({ length: current.length }, (_, i) => i),
+          });
+        }
+      }
+    } else if (isJsxBrElement(child)) {
+      out.push({ node: child, current: "\n" });
+    } else if (t.isJSXElement(child) || t.isJSXFragment(child)) {
+      collectTextRangePartsRaw(child, out);
+    }
+  }
+}
+
+function normalizeTextRangeParts(parts: TextRangePart[]): TextRangePart[] {
+  return parts.flatMap((part, index): TextRangePart[] => {
+    if (!("raw" in part)) return [part];
+    let start = 0;
+    let end = part.current.length;
+    if (parts[index - 1]?.current === "\n") {
+      while (start < end && /\s/.test(part.current[start] ?? "")) start++;
+    }
+    if (parts[index + 1]?.current === "\n") {
+      while (end > start && /\s/.test(part.current[end - 1] ?? "")) end--;
+    }
+    if (start === 0 && end === part.current.length) return [part];
+    if (start >= end) return [];
+    return [
+      {
+        ...part,
+        current: part.current.slice(start, end),
+        offsets: part.offsets.slice(start, end),
+      },
+    ];
+  });
+}
+
+function resetValueForRangeStyle(key: string): string | null {
+  if (key === "fontWeight") return "400";
+  if (key === "fontStyle") return "normal";
+  return null;
+}
+
+function styleSpanForText(
+  text: string,
+  key: string,
+  value: string | null,
+): string {
+  const styleValue = value ?? resetValueForRangeStyle(key);
+  if (styleValue === null) return formatJsxText(text);
+  return `<span style={{ ${key}: ${jsString(styleValue)} }}>${formatJsxText(text)}</span>`;
+}
+
+function textRangeContent(parts: TextRangePart[]): string {
+  return parts.map((part) => part.current).join("");
+}
+
+function compactText(value: string): string {
+  return value.replace(/\s+/g, "");
+}
+
+function textMatchesExpected(current: string, expected: string): boolean {
+  return current === expected || compactText(current) === compactText(expected);
+}
+
+function formatRichText(value: string, formatText = formatJsxText): string {
+  return value
+    .split("\n")
+    .map((part) => formatText(part))
+    .join("<br />");
+}
+
+function formatOptionalText(
+  value: string,
+  formatText: (v: string) => string,
+): string {
+  return value ? formatText(value) : "";
+}
+
+function textLeafSplice(part: TextRangeLeaf, value: string): Splice {
+  const rawRange = textLeafRawRange(part, 0, part.current.length);
+  if (!rawRange) return spliceRange(part.node, part.text(value));
+  const { rawStart, rawEnd } = rawRange;
+  return {
+    from: part.node.start ?? 0,
+    to: part.node.end ?? 0,
+    text: `${part.raw.slice(0, rawStart)}${formatRichText(value, part.text)}${part.raw.slice(rawEnd)}`,
+  };
+}
+
+function textLeafRawRange(
+  part: TextRangeLeaf,
+  start: number,
+  end: number,
+): { rawStart: number; rawEnd: number } | null {
+  if (start >= end) return null;
+  let first: number | null = null;
+  let last: number | null = null;
+  for (let i = start; i < end; i++) {
+    const offset = part.offsets[i];
+    if (offset === undefined) return null;
+    if (offset === null) continue;
+    first ??= offset;
+    last = offset;
+  }
+  if (first === null || last === null) return null;
+  return { rawStart: first, rawEnd: last + 1 };
+}
+
+function buildTextRangeReplaceSplices(
+  parts: TextRangePart[],
+  start: number,
+  end: number,
+  value: string,
+): Splice[] | { error: string } {
+  const splices: Splice[] = [];
+  let offset = 0;
+  let inserted = false;
+
+  for (const part of parts) {
+    const partStart = offset;
+    const partEnd = partStart + part.current.length;
+    offset = partEnd;
+
+    const overlaps = start < partEnd && end > partStart;
+    const insertsHere =
+      start === end && !inserted && start >= partStart && start <= partEnd;
+    if (!overlaps && !insertsHere) continue;
+
+    if ("raw" in part) {
+      const localStart = Math.max(start, partStart) - partStart;
+      const localEnd = overlaps
+        ? Math.min(end, partEnd) - partStart
+        : localStart;
+      const nextText = `${part.current.slice(0, localStart)}${inserted ? "" : value}${part.current.slice(localEnd)}`;
+      splices.push(textLeafSplice(part, nextText));
+    } else if (overlaps) {
+      splices.push(
+        spliceRange(part.node, inserted ? "" : formatRichText(value)),
+      );
+    } else if (insertsHere) {
+      const at =
+        start === partStart ? (part.node.start ?? 0) : (part.node.end ?? 0);
+      splices.push({ from: at, to: at, text: formatRichText(value) });
+    }
+
+    inserted = true;
+  }
+
+  if (!inserted && start === end && start === offset) {
+    const last = parts[parts.length - 1];
+    if (!last) return { error: "element has no editable text" };
+    if ("raw" in last) {
+      splices.push(textLeafSplice(last, `${last.current}${value}`));
+    } else {
+      splices.push({
+        from: last.node.end ?? 0,
+        to: last.node.end ?? 0,
+        text: formatRichText(value),
+      });
+    }
+  }
+
+  return splices;
+}
+
+function buildTextContentSplices(
+  element: t.JSXElement,
+  value: string,
+  prevText: string,
+): Splice[] | { error: string } {
+  const parts = collectTextRangeParts(element);
+  const current = textRangeContent(parts);
+  if (!textMatchesExpected(current, prevText)) {
+    return { error: "no text candidate matches the current value" };
+  }
+  const diff = textDiff(current, value);
+  if (diff.start === diff.end && diff.value === "") return [];
+  return buildTextRangeReplaceSplices(parts, diff.start, diff.end, diff.value);
+}
+
+function buildTextRangeStyleSplices(
+  ast: t.File,
+  source: string,
+  element: t.JSXElement,
+  start: number,
+  end: number,
+  op: { key: string; value: string | null },
+  prevText?: string,
+): Splice[] | { error: string } | null {
+  if (
+    !Number.isInteger(start) ||
+    !Number.isInteger(end) ||
+    start < 0 ||
+    end <= start
+  ) {
+    return { error: "invalid text range" };
+  }
+
+  const parts = collectTextRangeParts(element);
+  const renderedText = textRangeContent(parts);
+  const current = prevText ?? renderedText;
+  if (!current) return { error: "element has no editable text" };
+  if (end > current.length) return { error: "text range is out of bounds" };
+  if (prevText !== undefined && renderedText !== prevText) {
+    if (elementTextCandidateMatches(ast, element, prevText)) {
+      const result = buildStyleSplice(source, element, [op]);
+      if (result && "error" in result) return result;
+      return result ? [result] : [];
+    }
+    return { error: "no text candidate matches the current value" };
+  }
+
+  const splices: Splice[] = [];
+  let leafStart = 0;
+  for (const leaf of parts) {
+    const leafEnd = leafStart + leaf.current.length;
+    if (!("raw" in leaf)) {
+      leafStart = leafEnd;
+      continue;
+    }
+    const selectedStart = Math.max(start, leafStart);
+    const selectedEnd = Math.min(end, leafEnd);
+    if (selectedStart >= selectedEnd) {
+      leafStart = leafEnd;
+      continue;
+    }
+
+    if (
+      selectedStart === leafStart &&
+      selectedEnd === leafEnd &&
+      t.isJSXElement(leaf.parent) &&
+      leaf.parent !== element &&
+      isOnlyMeaningfulChild(leaf.parent, leaf.node)
+    ) {
+      const result = buildStyleSplice(source, leaf.parent, [op]);
+      if (result && "error" in result) return result;
+      if (result) splices.push(result);
+      leafStart = leafEnd;
+      continue;
+    }
+
+    const localStart = selectedStart - leafStart;
+    const localEnd = selectedEnd - leafStart;
+    const rawRange = textLeafRawRange(leaf, localStart, localEnd);
+    if (!rawRange) return { error: "text range source mismatch" };
+    const raw = leaf.raw;
+    const { rawStart, rawEnd } = rawRange;
+    const before = raw.slice(0, rawStart);
+    const selected = leaf.current.slice(localStart, localEnd);
+    const after = raw.slice(rawEnd);
+    const beforeText = t.isJSXText(leaf.node)
+      ? before
+      : formatOptionalText(before, leaf.text);
+    const afterText = t.isJSXText(leaf.node)
+      ? after
+      : formatOptionalText(after, leaf.text);
+    splices.push(
+      spliceRange(
+        leaf.node,
+        `${beforeText}${styleSpanForText(selected, op.key, op.value)}${afterText}`,
+      ),
+    );
+    leafStart = leafEnd;
+  }
+
+  return splices.length > 0 ? splices : null;
+}
+
+// `<Wrap>{children}</Wrap>` and `<h2>{title}</h2>` — sole child is a
+// JSXExpressionContainer wrapping a bare Identifier. Returns the identifier
+// name; callers branch on `'children'` vs. a generic prop passthrough.
+function propPassthroughName(element: t.JSXElement): string | null {
+  const meaningful = meaningfulChildren(element);
+  if (meaningful.length !== 1) return null;
+  const child = meaningful[0];
+  if (!t.isJSXExpressionContainer(child)) return null;
+  return t.isIdentifier(child.expression) ? child.expression.name : null;
+}
+
+type EnclosingComponent = {
+  name: string;
+  fn: t.FunctionDeclaration | t.FunctionExpression | t.ArrowFunctionExpression;
+};
+
+// Smallest top-level capitalized function whose body covers `target`.
+function findEnclosingComponent(
+  ast: t.File,
+  target: t.Node,
+): EnclosingComponent | null {
+  let best: EnclosingComponent | null = null;
+  let bestSize = Number.POSITIVE_INFINITY;
+  const targetStart = target.start ?? 0;
+  const targetEnd = target.end ?? 0;
+  const consider = (name: string, fn: EnclosingComponent["fn"]) => {
+    if (!/^[A-Z]/.test(name)) return;
+    const fnStart = fn.start ?? 0;
+    const fnEnd = fn.end ?? 0;
+    if (fnStart > targetStart || fnEnd < targetEnd) return;
+    const size = fnEnd - fnStart;
+    if (size < bestSize) {
+      best = { name, fn };
+      bestSize = size;
+    }
+  };
+  const visitDecl = (decl: t.Statement) => {
+    if (t.isFunctionDeclaration(decl) && decl.id) {
+      consider(decl.id.name, decl);
+    } else if (t.isVariableDeclaration(decl)) {
+      for (const d of decl.declarations) {
+        if (!t.isVariableDeclarator(d) || !t.isIdentifier(d.id) || !d.init)
+          continue;
+        if (
+          t.isArrowFunctionExpression(d.init) ||
+          t.isFunctionExpression(d.init)
+        ) {
+          consider(d.id.name, d.init);
+        }
+      }
+    }
+  };
+  for (const decl of ast.program.body) {
+    visitDecl(decl);
+    if (
+      t.isExportNamedDeclaration(decl) ||
+      t.isExportDefaultDeclaration(decl)
+    ) {
+      const inner = decl.declaration;
+      if (inner && (t.isStatement(inner) || t.isFunctionDeclaration(inner))) {
+        visitDecl(inner as t.Statement);
+      }
+    }
+  }
+  return best;
+}
+
+function componentDestructuresProp(
+  fn: EnclosingComponent["fn"],
+  propName: string,
+): boolean {
+  if (fn.params.length === 0) return false;
+  let first: t.Node = fn.params[0];
+  // Handle `({ title }: Props = defaults)` — strip the default-value wrapper.
+  if (t.isAssignmentPattern(first)) first = first.left;
+  if (!t.isObjectPattern(first)) return false;
+  for (const prop of first.properties) {
+    if (!t.isObjectProperty(prop)) continue;
+    if (t.isIdentifier(prop.key) && prop.key.name === propName) return true;
+    if (t.isStringLiteral(prop.key) && prop.key.value === propName) return true;
+  }
+  return false;
+}
+
+function collectCallSiteCandidates(
+  ast: t.Node,
+  componentName: string,
+): TextCandidate[] {
+  const out: TextCandidate[] = [];
+  walkJsx(ast, (n) => {
+    if (!t.isJSXElement(n)) return;
+    const elName = n.openingElement.name;
+    if (t.isJSXIdentifier(elName) && elName.name === componentName) {
+      collectTextCandidates(n, out);
+    }
+  });
+  return out;
+}
+
+function collectPropCallSiteCandidates(
+  ast: t.Node,
+  componentName: string,
+  propName: string,
+): TextCandidate[] {
+  const out: TextCandidate[] = [];
+  walkJsx(ast, (n) => {
+    if (!t.isJSXElement(n)) return;
+    const elName = n.openingElement.name;
+    if (!t.isJSXIdentifier(elName) || elName.name !== componentName) return;
+    const attr = findJsxAttr(n.openingElement, propName);
+    if (!attr?.value) return; // shorthand-true: not editable text.
+    const v = attr.value;
+    if (t.isStringLiteral(v)) {
+      out.push({
+        current: v.value,
+        splice: (s) => spliceRange(v, formatJsxAttrValue(s)),
+      });
+    } else if (t.isJSXExpressionContainer(v)) {
+      const expr = v.expression;
+      if (t.isStringLiteral(expr) || t.isNumericLiteral(expr)) {
+        out.push({
+          current: String(expr.value),
+          splice: (s) => spliceRange(v, formatJsxAttrValue(s)),
+        });
+      }
+    }
+  });
+  return out;
+}
+
+// Smallest enclosing `arr.map((p) => …)` callback (or `.flatMap`) that
+// covers `target`. Returns the callback fn plus the array argument node.
+function findEnclosingMapCallback(
+  ast: t.Node,
+  target: t.Node,
+): {
+  fn: t.ArrowFunctionExpression | t.FunctionExpression;
+  arrayArg: t.Expression;
+} | null {
+  type Best = {
+    fn: t.ArrowFunctionExpression | t.FunctionExpression;
+    arrayArg: t.Expression;
+    size: number;
+  };
+  let best: Best | null = null;
+  const targetStart = target.start ?? 0;
+  const targetEnd = target.end ?? 0;
+  walkAll(ast, (node) => {
+    if (!t.isCallExpression(node)) return;
+    const callee = node.callee;
+    if (!t.isMemberExpression(callee) || callee.computed) return;
+    if (!t.isIdentifier(callee.property)) return;
+    if (callee.property.name !== "map" && callee.property.name !== "flatMap")
+      return;
+    const fn = node.arguments[0];
+    if (
+      !fn ||
+      (!t.isArrowFunctionExpression(fn) && !t.isFunctionExpression(fn))
+    )
+      return;
+    const fnStart = fn.start ?? 0;
+    const fnEnd = fn.end ?? 0;
+    if (fnStart > targetStart || fnEnd < targetEnd) return;
+    if (!t.isExpression(callee.object)) return;
+    const size = fnEnd - fnStart;
+    if (!best || size < best.size) best = { fn, arrayArg: callee.object, size };
+  });
+  if (!best) return null;
+  const found: Best = best;
+  return { fn: found.fn, arrayArg: found.arrayArg };
+}
+
+type ArrayElement = t.Expression | t.SpreadElement;
+
+// `[ {...}, {...} ]` literal, either inline or via a `const x = [ ... ]`
+// declaration the receiver resolves to. Returns the ArrayExpression's
+// element list, or null if we can't resolve to a literal.
+function resolveArrayLiteralElements(
+  ast: t.Node,
+  expr: t.Expression,
+): ArrayElement[] | null {
+  const dropHoles = (arr: t.ArrayExpression): ArrayElement[] =>
+    arr.elements.filter((e): e is ArrayElement => e != null);
+  if (t.isArrayExpression(expr)) return dropHoles(expr);
+  if (!t.isIdentifier(expr)) return null;
+  const name = expr.name;
+  const useStart = expr.start ?? 0;
+  let init: t.ArrayExpression | null = null;
+  walkAll(ast, (node) => {
+    if (!t.isVariableDeclarator(node)) return;
+    if (!t.isIdentifier(node.id) || node.id.name !== name) return;
+    if (!node.init || !t.isArrayExpression(node.init)) return;
+    // Must be declared before the use site; pick the most local match.
+    if ((node.init.start ?? 0) > useStart) return;
+    init = node.init;
+  });
+  return init ? dropHoles(init) : null;
+}
+
+function findObjectProperty(
+  obj: t.Node,
+  name: string,
+): t.ObjectProperty | null {
+  if (!t.isObjectExpression(obj)) return null;
+  for (const prop of obj.properties) {
+    if (!t.isObjectProperty(prop) || prop.computed) continue;
+    if (t.isIdentifier(prop.key) && prop.key.name === name) return prop;
+    if (t.isStringLiteral(prop.key) && prop.key.value === name) return prop;
+  }
+  return null;
+}
+
+// Decode `{p.field}` (MemberExpression) or `{field}` (Identifier
+// destructured from the callback param) into a single field name.
+function decodeMapPassthrough(
+  element: t.JSXElement,
+  callbackParam: t.Node | undefined,
+): string | null {
+  const meaningful = meaningfulChildren(element);
+  if (meaningful.length !== 1) return null;
+  const child = meaningful[0];
+  if (!t.isJSXExpressionContainer(child)) return null;
+  const expr = child.expression;
+
+  if (t.isMemberExpression(expr)) {
+    if (expr.computed) return null;
+    if (!t.isIdentifier(expr.object) || !t.isIdentifier(expr.property))
+      return null;
+    if (!callbackParam || !t.isIdentifier(callbackParam)) return null;
+    if (callbackParam.name !== expr.object.name) return null;
+    return expr.property.name;
+  }
+
+  if (t.isIdentifier(expr)) {
+    const fieldName = expr.name;
+    // Param is `{ field, ... }` destructuring — the identifier names the
+    // destructured property. Skip alias/rename forms (`{ field: alias }`).
+    if (!callbackParam || !t.isObjectPattern(callbackParam)) return null;
+    for (const prop of callbackParam.properties) {
+      if (!t.isObjectProperty(prop) || prop.computed) continue;
+      if (!t.isIdentifier(prop.key) || prop.key.name !== fieldName) continue;
+      // Shorthand `{ field }` → value is also an Identifier with same name.
+      // Aliased `{ field: other }` → value is a different identifier; skip.
+      return t.isIdentifier(prop.value) && prop.value.name === fieldName
+        ? fieldName
+        : null;
+    }
+  }
+
+  return null;
+}
+
+function collectArrayMapCandidates(
+  ast: t.Node,
+  element: t.JSXElement,
+): TextCandidate[] {
+  const ctx = findEnclosingMapCallback(ast, element);
+  if (!ctx) return [];
+  const fieldName = decodeMapPassthrough(element, ctx.fn.params[0]);
+  if (!fieldName) return [];
+  const elements = resolveArrayLiteralElements(ast, ctx.arrayArg);
+  if (!elements) return [];
+  const out: TextCandidate[] = [];
+  for (const obj of elements) {
+    const prop = findObjectProperty(obj, fieldName);
+    if (!prop) continue;
+    const v = prop.value;
+    if (t.isStringLiteral(v)) {
+      out.push({
+        current: v.value,
+        splice: (s) => spliceRange(v, jsString(s)),
+      });
+    } else if (t.isNumericLiteral(v)) {
+      out.push({
+        current: String(v.value),
+        splice: (s) => spliceRange(v, jsString(s)),
+      });
+    }
+  }
+  return out;
+}
+
+function collectElementTextCandidates(
+  ast: t.File,
+  element: t.JSXElement,
+): TextCandidate[] {
+  const candidates: TextCandidate[] = [];
+  collectTextCandidates(element, candidates);
+  if (candidates.length === 0) {
+    const passthrough = propPassthroughName(element);
+    const enclosing = passthrough ? findEnclosingComponent(ast, element) : null;
+    if (passthrough === "children" && enclosing) {
+      candidates.push(...collectCallSiteCandidates(ast, enclosing.name));
+    } else if (
+      passthrough &&
+      enclosing &&
+      componentDestructuresProp(enclosing.fn, passthrough)
+    ) {
+      candidates.push(
+        ...collectPropCallSiteCandidates(ast, enclosing.name, passthrough),
+      );
+    }
+  }
+  if (candidates.length === 0) {
+    candidates.push(...collectArrayMapCandidates(ast, element));
+  }
+  return candidates;
+}
+
+function elementTextCandidateMatches(
+  ast: t.File,
+  element: t.JSXElement,
+  prevText: string,
+): boolean {
+  const norm = prevText.trim();
+  return collectElementTextCandidates(ast, element).some(
+    (candidate) => candidate.current === norm,
+  );
+}
+
+function buildTextSplice(
+  ast: t.File,
+  element: t.JSXElement,
+  value: string,
+  prevText?: string,
+): Splice | { error: string } {
+  const candidates = collectElementTextCandidates(ast, element);
+  if (candidates.length === 0) {
+    return { error: "element has no editable text" };
+  }
+  if (candidates.length === 1) {
+    return candidates[0].splice(value);
+  }
+  if (prevText === undefined) {
+    return { error: "element has multiple text candidates; missing prevText" };
+  }
+  // Trim: JSX collapses surrounding whitespace at render time, so the
+  // DOM `prevText` won't have leading/trailing space the source might.
+  const norm = prevText.trim();
+  const matches = candidates.filter((c) => c.current === norm);
+  if (matches.length === 0) {
+    return { error: "no text candidate matches the current value" };
+  }
+  if (matches.length > 1) {
+    return {
+      error:
+        "multiple text candidates share the same value; cannot disambiguate",
+    };
+  }
+  return matches[0].splice(value);
+}
+
+type AssetEditPlan = {
+  attrSplice: Splice;
+};
+
+function planAssetAttr(
+  element: t.JSXElement,
+  attr: string,
+  assetId: string,
+): AssetEditPlan | { error: string } {
+  if (
+    attr !== "src" ||
+    !t.isJSXIdentifier(element.openingElement.name) ||
+    element.openingElement.name.name !== "img"
+  ) {
+    return { error: "uploaded assets can only set img src" };
+  }
+  if (!/^[A-Za-z0-9_-]{1,200}$/.test(assetId)) {
+    return { error: "invalid uploaded asset id" };
+  }
+
+  const opening = element.openingElement;
+  const assetRef = `asset://${assetId}`;
+  const newAttr = `${attr}=${formatJsxAttrValue(assetRef)}`;
+  const existing = findJsxAttr(opening, attr);
+  const attrSplice: Splice = existing
+    ? { from: existing.start ?? 0, to: existing.end ?? 0, text: newAttr }
+    : {
+        from: opening.name.end ?? 0,
+        to: opening.name.end ?? 0,
+        text: ` ${newAttr}`,
+      };
+  return { attrSplice };
+}
+
+type PlaceholderEditPlan = {
+  elementSplice: Splice;
+};
+
+function planReplacePlaceholder(
+  element: t.JSXElement,
+  assetId: string,
+): PlaceholderEditPlan | { error: string } {
+  const opening = element.openingElement;
+  if (
+    !t.isJSXIdentifier(opening.name) ||
+    opening.name.name !== "ImagePlaceholder"
+  ) {
+    return { error: "not a placeholder" };
+  }
+  if (!/^[A-Za-z0-9_-]{1,200}$/.test(assetId))
+    return { error: "invalid uploaded asset id" };
+
+  const hint =
+    readJsxStringAttr(opening, "label") ??
+    readJsxStringAttr(opening, "hint") ??
+    "";
+  const width = readJsxNumberAttr(opening, "width");
+  const height = readJsxNumberAttr(opening, "height");
+
+  const styleParts: string[] = [];
+  if (width != null) styleParts.push(`width: ${width}`);
+  else if (height != null) styleParts.push(`width: '100%'`);
+  if (height != null) styleParts.push(`height: ${height}`);
+  else if (width != null) styleParts.push(`height: '100%'`);
+  styleParts.push(`objectFit: 'cover'`);
+  styleParts.push(`objectPosition: '50% 50%'`);
+  const replacement =
+    `<img src=${formatJsxAttrValue(`asset://${assetId}`)} alt=${jsString(hint)} ` +
+    `style={{ ${styleParts.join(", ")} }} />`;
+
+  return { elementSplice: spliceRange(element, replacement) };
+}
+
+function planInsertImageAsset(
+  source: string,
+  element: t.JSXElement,
+  assetId: string,
+  alt: string,
+): Splice[] | { error: string } {
+  if (!/^[A-Za-z0-9_-]{1,200}$/.test(assetId)) {
+    return { error: "invalid uploaded asset id" };
+  }
+  if (!t.isJSXIdentifier(element.openingElement.name)) {
+    return { error: "image can only be inserted into a named JSX element" };
+  }
+
+  const opening = element.openingElement;
+  const img =
+    `<img src=${formatJsxAttrValue(`asset://${assetId}`)} alt=${formatJsxAttrValue(alt)} ` +
+    `style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'cover', zIndex: -1 }} />`;
+  const stylePosition = findJsxAttr(opening, "style");
+  let needsRelativePosition = !stylePosition;
+  let needsIsolation = !stylePosition;
+  if (
+    stylePosition &&
+    t.isJSXExpressionContainer(stylePosition.value) &&
+    t.isObjectExpression(stylePosition.value.expression)
+  ) {
+    let hasPosition = false;
+    let existingPosition: string | undefined;
+    let hasIsolation = false;
+    for (const property of stylePosition.value.expression.properties) {
+      if (!t.isObjectProperty(property) || property.computed) continue;
+      const key = t.isIdentifier(property.key)
+        ? property.key.name
+        : t.isStringLiteral(property.key)
+          ? property.key.value
+          : undefined;
+      if (key === "position") {
+        hasPosition = true;
+        if (t.isStringLiteral(property.value)) {
+          existingPosition = property.value.value;
+        }
+      }
+      if (key === "isolation") hasIsolation = true;
+    }
+    needsRelativePosition = !hasPosition || existingPosition === "static";
+    needsIsolation = !hasIsolation;
+  } else if (stylePosition) {
+    needsRelativePosition = false;
+    needsIsolation = false;
+  }
+  const styleOps = [
+    ...(needsRelativePosition ? [{ key: "position", value: "relative" }] : []),
+    ...(needsIsolation ? [{ key: "isolation", value: "isolate" }] : []),
+  ];
+  const style = styleOps.length
+    ? buildStyleSplice(source, element, styleOps)
+    : null;
+  if (style && "error" in style) return { error: style.error };
+  const styleSplice = style && !("error" in style) ? style : null;
+
+  if (opening.selfClosing) {
+    const tagName = element.openingElement.name.name;
+    let openingText = source.slice(opening.start ?? 0, opening.end ?? 0);
+    if (styleSplice) {
+      const from = (styleSplice.from ?? 0) - (opening.start ?? 0);
+      const to = (styleSplice.to ?? 0) - (opening.start ?? 0);
+      openingText =
+        openingText.slice(0, from) + styleSplice.text + openingText.slice(to);
+    }
+    const expandedOpening = openingText.replace(/\/\s*>$/, ">");
+    if (expandedOpening === openingText) {
+      return { error: "could not expand the slide root element" };
+    }
+    return [
+      {
+        from: element.start ?? 0,
+        to: element.end ?? 0,
+        text: `${expandedOpening}${img}</${tagName}>`,
+      },
+    ];
+  }
+
+  if (!element.closingElement) {
+    return { error: "slide root has no closing element" };
+  }
+  return [
+    ...(styleSplice ? [styleSplice] : []),
+    { from: opening.end ?? 0, to: opening.end ?? 0, text: img },
+  ];
+}
+
+export function applyEdit(
+  source: string,
+  line: number,
+  column: number,
+  ops: EditOp[],
+): ApplyEditResult {
+  const plan = planEdit(source, line, column, ops);
+  if (!plan.ok) return plan;
+  return plan.splices.length
+    ? applySplices(source, plan.splices)
+    : { ok: true, source };
+}
+
+export function planEdit(
+  source: string,
+  line: number,
+  column: number,
+  ops: EditOp[],
+  exactLocation = false,
+):
+  | { ok: true; splices: Splice[] }
+  | { ok: false; status: number; error: string } {
+  if (ops.length === 0) return { ok: true, splices: [] };
+
+  const ast = parseSource(source);
+  if (!ast) return { ok: false, status: 422, error: "could not parse source" };
+  const element = exactLocation
+    ? findJsxByStart(ast, line, column)
+    : findElementForEdit(ast, line, column, ops);
+  if (!element)
+    return { ok: false, status: 422, error: "no JSX element at location" };
+
+  const splices: Splice[] = [];
+
+  const styleOps = ops.flatMap((op) =>
+    op.kind === "set-style" ? [{ key: op.key, value: op.value }] : [],
+  );
+  if (styleOps.length > 0) {
+    const result = buildStyleSplice(source, element, styleOps);
+    if (result && "error" in result) {
+      return { ok: false, status: 422, error: result.error };
+    }
+    if (result) splices.push(result);
+  }
+
+  for (const op of ops) {
+    if (op.kind !== "set-text-range-style") continue;
+    const result = buildTextRangeStyleSplices(
+      ast,
+      source,
+      element,
+      op.start,
+      op.end,
+      { key: op.key, value: op.value },
+      op.prevText,
+    );
+    if (result && "error" in result)
+      return { ok: false, status: 422, error: result.error };
+    if (result) splices.push(...result);
+  }
+
+  for (const op of ops) {
+    if (op.kind !== "set-text") continue;
+    if (
+      op.prevText !== undefined &&
+      (op.value.includes("\n") || op.prevText.includes("\n"))
+    ) {
+      const richResult = buildTextContentSplices(
+        element,
+        op.value,
+        op.prevText,
+      );
+      if (!("error" in richResult)) {
+        splices.push(...richResult);
+        continue;
+      }
+    }
+    const result = buildTextSplice(ast, element, op.value, op.prevText);
+    if ("error" in result) {
+      if (op.prevText === undefined)
+        return { ok: false, status: 422, error: result.error };
+      const richResult = buildTextContentSplices(
+        element,
+        op.value,
+        op.prevText,
+      );
+      if ("error" in richResult)
+        return { ok: false, status: 422, error: result.error };
+      splices.push(...richResult);
+    } else {
+      splices.push(result);
+    }
+  }
+
+  const assetOps = ops.flatMap((op) =>
+    op.kind === "set-attr-asset" ? [op] : [],
+  );
+  const placeholderOps = ops.flatMap((op) =>
+    op.kind === "replace-placeholder-with-image" ? [op] : [],
+  );
+  const insertImageOps = ops.flatMap((op) =>
+    op.kind === "insert-image-asset" ? [op] : [],
+  );
+  if (
+    assetOps.length > 0 ||
+    placeholderOps.length > 0 ||
+    insertImageOps.length > 0
+  ) {
+    for (const op of assetOps) {
+      const plan = planAssetAttr(element, op.attr, op.assetId);
+      if ("error" in plan) return { ok: false, status: 422, error: plan.error };
+      splices.push(plan.attrSplice);
+    }
+    for (const op of placeholderOps) {
+      const plan = planReplacePlaceholder(element, op.assetId);
+      if ("error" in plan) return { ok: false, status: 422, error: plan.error };
+      splices.push(plan.elementSplice);
+    }
+    for (const op of insertImageOps) {
+      const plan = planInsertImageAsset(source, element, op.assetId, op.alt);
+      if ("error" in plan) return { ok: false, status: 422, error: plan.error };
+      splices.push(...plan);
+    }
+  }
+
+  return { ok: true, splices };
+}