@vgai/editor 0.2.0

package/src/ui-source/writer.ts

@@ -0,0 +1,1175 @@
+/**
+ * Surgical source writer (C7/C8) — the visual-edit "edit source by offset, not by
+ * AST rewrite" trick. Given the original source and an element's location (from the
+ * OID index), it edits the inline `style={{…}}` object IN PLACE, preserving all
+ * other properties (including dynamic ones), formatting, and comments — and refuses
+ * to touch expression-bound (dynamic) values (the literal-vs-dynamic guard). Plus a
+ * structural delete. Pure string ops (no parser, like visual-edit/writer.ts).
+ */
+
+export interface StyleProperty {
+  name: string;
+  /** Raw value text as it appears in source. */
+  raw: string;
+  literal: boolean;
+  valueStart: number;
+  valueEnd: number;
+  /**
+   * The full `key: value` member span — from the first char of the key through the
+   * end of the (trimmed) value, EXCLUDING any leading/trailing whitespace or the
+   * separating comma (D-A2, `removeInlineStyle`). `memberEnd` always equals
+   * `valueEnd` (the member ends exactly where its value ends); kept as a distinct
+   * field for readability at removeInlineStyle's call site.
+   */
+  memberStart: number;
+  memberEnd: number;
+}
+
+/** Find the `>` that closes the opening tag starting at `start` (a `<`). */
+export function findTagEnd(code: string, start: number): number {
+  let depth = 0;
+  let str: string | null = null;
+  for (let i = start; i < code.length; i++) {
+    const c = code[i];
+    if (str) {
+      if (c === str && code[i - 1] !== '\\') str = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') str = c;
+    else if (c === '{') depth++;
+    else if (c === '}') depth--;
+    else if (c === '>' && depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Locate the inner range of `style={{ … }}` within the opening tag, or null. */
+function findStyleObject(
+  code: string,
+  tagStart: number,
+  tagEnd: number,
+): { innerStart: number; innerEnd: number } | null {
+  const seg = code.slice(tagStart, tagEnd);
+  const m = seg.match(/style\s*=\s*\{\{/);
+  if (!m || m.index == null) return null;
+  const openBraceOuter = tagStart + m.index + m[0].length - 2; // position of first `{` of `{{`
+  // inner object starts after the two `{`
+  const innerStart = openBraceOuter + 2;
+  // find the matching `}}` for the object: track brace depth from innerStart
+  let depth = 2; // we are inside two open braces
+  let str: string | null = null;
+  for (let i = innerStart; i < tagEnd + 2 && i < code.length; i++) {
+    const c = code[i];
+    if (str) {
+      if (c === str && code[i - 1] !== '\\') str = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') str = c;
+    else if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 1) {
+        // this `}` closes the object (one brace — the expression brace — remains)
+        return { innerStart, innerEnd: i };
+      }
+    }
+  }
+  return null;
+}
+
+const LITERAL_RE = /^\s*('[^']*'|"[^"]*"|`[^`]*`|-?\d+(\.\d+)?(px|em|rem|%|vh|vw)?)\s*$/;
+
+/** Parse the top-level properties of a style object body (between the braces). */
+export function analyzeStyleProperties(objBody: string, baseOffset: number): StyleProperty[] {
+  const props: StyleProperty[] = [];
+  let i = 0;
+  const n = objBody.length;
+  let str: string | null = null;
+  let depth = 0;
+  let keyStart = -1;
+  let colon = -1;
+  const flush = (end: number): void => {
+    if (keyStart >= 0 && colon >= 0) {
+      const name = objBody.slice(keyStart, colon).replace(/['"]/g, '').trim();
+      const raw = objBody.slice(colon + 1, end);
+      if (name) {
+        const trimmed = raw.trim();
+        const lead = raw.length - raw.trimStart().length;
+        // A template literal with `${...}` interpolation is DYNAMIC, not literal,
+        // even though it is delimited by backticks — never let it be editable.
+        const isLiteral = LITERAL_RE.test(raw) && !trimmed.includes('${');
+        const valueStart = baseOffset + colon + 1 + lead;
+        const valueEnd = valueStart + trimmed.length;
+        props.push({
+          name,
+          raw: trimmed,
+          literal: isLiteral,
+          valueStart,
+          valueEnd,
+          memberStart: baseOffset + keyStart,
+          memberEnd: valueEnd,
+        });
+      }
+    }
+    keyStart = -1;
+    colon = -1;
+  };
+  for (; i < n; i++) {
+    const c = objBody[i] as string;
+    if (str) {
+      if (c === str && objBody[i - 1] !== '\\') str = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      str = c;
+      continue;
+    }
+    if (c === '{' || c === '(' || c === '[') depth++;
+    else if (c === '}' || c === ')' || c === ']') depth--;
+    else if (depth === 0) {
+      if (c === ':' && colon < 0) colon = i;
+      else if (c === ',') {
+        flush(i);
+      } else if (keyStart < 0 && /\S/.test(c)) keyStart = i;
+    }
+  }
+  flush(n);
+  return props;
+}
+
+export interface StyleEditResult {
+  code: string;
+  changed: boolean;
+  /** True if the edit was refused because the existing value is a JS expression. */
+  dynamic: boolean;
+  /**
+   * D-A1 (wave 13, `docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md`): true ONLY when
+   * `setInlineStyle` took the APPEND branch — the element's style object had no
+   * literal (and no dynamic expression) for this prop before the write, e.g. it
+   * was absent entirely or spread-derived (`style={{ ...vars }}`). False/absent on
+   * a replace, a dynamic-value refusal, or a no-op. Undo must know this: replaying
+   * the write with the prior value would find the NOW-appended literal and REPLACE
+   * it — restoring a hardcoded value into a spot the source never had one — instead
+   * of removing the prop to truly restore the pre-edit source.
+   */
+  appended?: boolean;
+}
+
+/**
+ * Set an inline style property on the element at `elementStart` (a `<`). Replaces a
+ * literal value, refuses a dynamic one (guard), or appends a new property; inserts a
+ * `style={{…}}` if none exists. Other properties are untouched.
+ */
+export function setInlineStyle(
+  code: string,
+  elementStart: number,
+  prop: string,
+  value: string | number,
+): StyleEditResult {
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return { code, changed: false, dynamic: false };
+  // Escape the value so a quote/backslash can't break source syntax.
+  const valueText =
+    typeof value === 'number'
+      ? String(value)
+      : `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  const styleObj = findStyleObject(code, elementStart, tagEnd);
+
+  if (styleObj) {
+    const body = code.slice(styleObj.innerStart, styleObj.innerEnd);
+    const props = analyzeStyleProperties(body, styleObj.innerStart);
+    const existing = props.find((p) => p.name === prop);
+    if (existing) {
+      if (!existing.literal) return { code, changed: false, dynamic: true }; // guard
+      const next = code.slice(0, existing.valueStart) + valueText + code.slice(existing.valueEnd);
+      return { code: next, changed: true, dynamic: false };
+    }
+    // append a property, preserving existing content
+    const trimmedBody = body.trimEnd();
+    const sep = trimmedBody.length === 0 ? '' : trimmedBody.endsWith(',') ? ' ' : ', ';
+    const insertAt = styleObj.innerStart + trimmedBody.length;
+    const next = `${code.slice(0, insertAt)}${sep}${prop}: ${valueText}${code.slice(insertAt)}`;
+    return { code: next, changed: true, dynamic: false, appended: true };
+  }
+
+  // A whole-attribute dynamic style (`style={expr}`, single brace) exists but is
+  // not an editable object literal — refuse rather than appending a duplicate attr.
+  const openSeg = code.slice(elementStart, tagEnd);
+  if (/style\s*=\s*\{/.test(openSeg)) {
+    return { code, changed: false, dynamic: true };
+  }
+
+  // no style attr — insert before the tag end (handle self-closing `/>`)
+  const selfClose = code[tagEnd - 1] === '/';
+  const insertAt = selfClose ? tagEnd - 1 : tagEnd;
+  const next = `${code.slice(0, insertAt)} style={{ ${prop}: ${valueText} }}${code.slice(insertAt)}`;
+  return { code: next, changed: true, dynamic: false };
+}
+
+/**
+ * D-A2 (wave 13, `docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md`): surgically REMOVE a
+ * literal `prop: value` entry from the element's `style={{…}}` object at
+ * `elementStart` — the correct undo for a write that took `setInlineStyle`'s
+ * APPEND branch (`appended: true`). Fixes up the neighbouring separator/trailing
+ * comma so the remaining object stays syntactically valid; if `prop` was the
+ * object's ONLY content, collapses to an empty `style={{}}` rather than stripping
+ * the attribute entirely (keeps redo — a plain re-append — trivially reversible,
+ * and avoids re-deriving the whole-attribute insertion position `setInlineStyle`'s
+ * no-style-attr branch uses). `changed: false` (and no-op) if `prop` isn't present
+ * as a literal member at all — including a DYNAMIC member (mirrors
+ * `setInlineStyle`'s literal-vs-dynamic guard: never remove an expression-bound
+ * value the caller didn't write).
+ */
+export function removeInlineStyle(
+  code: string,
+  elementStart: number,
+  prop: string,
+): StyleEditResult {
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return { code, changed: false, dynamic: false };
+  const styleObj = findStyleObject(code, elementStart, tagEnd);
+  if (!styleObj) return { code, changed: false, dynamic: false }; // no style attr — nothing to remove
+
+  const body = code.slice(styleObj.innerStart, styleObj.innerEnd);
+  const props = analyzeStyleProperties(body, styleObj.innerStart);
+  const existing = props.find((p) => p.name === prop);
+  if (!existing) return { code, changed: false, dynamic: false }; // absent — nothing to remove
+  if (!existing.literal) return { code, changed: false, dynamic: true }; // guard, mirrors setInlineStyle
+
+  // Prefer consuming a comma that FOLLOWS this member (it precedes others in the
+  // list); else one that PRECEDES it (it is last); else this was the ONLY thing in
+  // the object — collapse to `{}` instead.
+  let after = existing.memberEnd;
+  while (after < styleObj.innerEnd && /\s/.test(code[after] ?? '')) after++;
+  if (code[after] === ',') {
+    let end = after + 1;
+    if (code[end] === ' ') end++;
+    return {
+      code: code.slice(0, existing.memberStart) + code.slice(end),
+      changed: true,
+      dynamic: false,
+    };
+  }
+
+  let before = existing.memberStart - 1;
+  while (before >= styleObj.innerStart && /\s/.test(code[before] ?? '')) before--;
+  if (code[before] === ',') {
+    return {
+      code: code.slice(0, before) + code.slice(existing.memberEnd),
+      changed: true,
+      dynamic: false,
+    };
+  }
+
+  return {
+    code: code.slice(0, styleObj.innerStart) + code.slice(styleObj.innerEnd),
+    changed: true,
+    dynamic: false,
+  };
+}
+
+/**
+ * Find the end (exclusive) of a full JSX element starting at `<Tag` — balancing
+ * nested same-tag elements and skipping `{…}` expressions and strings (C8).
+ */
+export function findElementEnd(code: string, start: number): number {
+  const tagEnd = findTagEnd(code, start);
+  if (tagEnd < 0) return -1;
+  if (code[tagEnd - 1] === '/') return tagEnd + 1; // self-closing
+  const tagNameMatch = code.slice(start + 1, tagEnd).match(/^([A-Za-z0-9_.]+)/);
+  const tag = tagNameMatch?.[1];
+  if (!tag) return -1;
+  let depth = 1;
+  let i = tagEnd + 1;
+  let str: string | null = null;
+  while (i < code.length && depth > 0) {
+    const c = code[i];
+    if (str) {
+      if (c === str && code[i - 1] !== '\\') str = null;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      str = c;
+      i++;
+      continue;
+    }
+    if (code.startsWith(`<${tag}`, i) && /[\s/>]/.test(code[i + 1 + tag.length] ?? '')) {
+      // A nested SAME-TAG element: only a non-self-closing one increments depth.
+      // A self-closing `<tag .../>` opens+closes in one tag and must NOT bump depth
+      // (else the balancer runs past the real closing tag and over-deletes).
+      const nestedTagEnd = findTagEnd(code, i);
+      if (nestedTagEnd > 0 && code[nestedTagEnd - 1] === '/') {
+        i = nestedTagEnd + 1; // skip the self-closing nested element whole
+      } else {
+        depth++;
+        i += 1 + tag.length;
+      }
+    } else if (code.startsWith(`</${tag}`, i)) {
+      depth--;
+      const close = code.indexOf('>', i);
+      i = close + 1;
+      if (depth === 0) return i;
+    } else {
+      i++;
+    }
+  }
+  return i;
+}
+
+// --- F5: multi-path style routing (inline handled above; className below) ---
+
+/**
+ * Encode a CSS prop:value as a Tailwind-style utility class. Numeric/color values
+ * use ARBITRARY values (`w-[200px]`, `bg-[#059669]`) so the round-trip is LOSSLESS
+ * (a named utility like `bg-emerald-600` would NOT recover the exact hex). Enums map
+ * to named utilities. This is the lossless-encoding rule from visual-edit/tailwind-map.
+ */
+// Cap 6 (React visual-edit parity): broadened to the grouped-inspector property set. Enum
+// values map to NAMED utilities; each named utility string is unique across groups so the
+// ENUM_GROUP reverse map (dedupe) stays unambiguous.
+const ENUM_UTILITIES: Record<string, Record<string, string>> = {
+  display: {
+    flex: 'flex',
+    block: 'block',
+    grid: 'grid',
+    inline: 'inline',
+    'inline-block': 'inline-block',
+    'inline-flex': 'inline-flex',
+    none: 'hidden',
+  },
+  flexDirection: {
+    row: 'flex-row',
+    column: 'flex-col',
+    'row-reverse': 'flex-row-reverse',
+    'column-reverse': 'flex-col-reverse',
+  },
+  flexWrap: { wrap: 'flex-wrap', nowrap: 'flex-nowrap', 'wrap-reverse': 'flex-wrap-reverse' },
+  justifyContent: {
+    'flex-start': 'justify-start',
+    'flex-end': 'justify-end',
+    center: 'justify-center',
+    'space-between': 'justify-between',
+    'space-around': 'justify-around',
+    'space-evenly': 'justify-evenly',
+  },
+  alignItems: {
+    'flex-start': 'items-start',
+    'flex-end': 'items-end',
+    center: 'items-center',
+    baseline: 'items-baseline',
+    stretch: 'items-stretch',
+  },
+  textAlign: {
+    left: 'text-left',
+    center: 'text-center',
+    right: 'text-right',
+    justify: 'text-justify',
+  },
+  position: {
+    relative: 'relative',
+    absolute: 'absolute',
+    fixed: 'fixed',
+    sticky: 'sticky',
+    static: 'static',
+  },
+  overflow: {
+    visible: 'overflow-visible',
+    hidden: 'overflow-hidden',
+    scroll: 'overflow-scroll',
+    auto: 'overflow-auto',
+  },
+  borderStyle: {
+    none: 'border-none',
+    solid: 'border-solid',
+    dashed: 'border-dashed',
+    dotted: 'border-dotted',
+    double: 'border-double',
+  },
+  textTransform: {
+    uppercase: 'uppercase',
+    lowercase: 'lowercase',
+    capitalize: 'capitalize',
+    none: 'normal-case',
+  },
+  whiteSpace: {
+    normal: 'whitespace-normal',
+    nowrap: 'whitespace-nowrap',
+    pre: 'whitespace-pre',
+    'pre-wrap': 'whitespace-pre-wrap',
+  },
+  fontStyle: { italic: 'italic', normal: 'not-italic' },
+  mixBlendMode: {
+    normal: 'mix-blend-normal',
+    multiply: 'mix-blend-multiply',
+    screen: 'mix-blend-screen',
+    overlay: 'mix-blend-overlay',
+  },
+};
+// Reverse map: a named utility -> its logical group (for dedupe of enum utilities).
+const ENUM_GROUP: Record<string, string> = (() => {
+  const out: Record<string, string> = {};
+  for (const [group, m] of Object.entries(ENUM_UTILITIES))
+    for (const u of Object.values(m)) out[u] = group;
+  return out;
+})();
+// Arbitrary-value utilities. `color`/`fontSize` both map to `text-`, so they use
+// Tailwind TYPE HINTS (`text-[color:..]` vs `text-[length:..]`) to disambiguate —
+// which also makes property-based dedupe unambiguous.
+const ARB_MAP: Record<string, { prefix: string; hint?: 'color' | 'length' }> = {
+  backgroundColor: { prefix: 'bg' },
+  // `border` covers both border-color and border-width, so — like `text-` — they use type
+  // hints to stay unambiguous for property-based dedupe (Cap 6).
+  borderColor: { prefix: 'border', hint: 'color' },
+  borderWidth: { prefix: 'border', hint: 'length' },
+  color: { prefix: 'text', hint: 'color' },
+  fontSize: { prefix: 'text', hint: 'length' },
+  width: { prefix: 'w' },
+  height: { prefix: 'h' },
+  minWidth: { prefix: 'min-w' },
+  minHeight: { prefix: 'min-h' },
+  maxWidth: { prefix: 'max-w' },
+  maxHeight: { prefix: 'max-h' },
+  padding: { prefix: 'p' },
+  paddingTop: { prefix: 'pt' },
+  paddingRight: { prefix: 'pr' },
+  paddingBottom: { prefix: 'pb' },
+  paddingLeft: { prefix: 'pl' },
+  margin: { prefix: 'm' },
+  marginTop: { prefix: 'mt' },
+  marginRight: { prefix: 'mr' },
+  marginBottom: { prefix: 'mb' },
+  marginLeft: { prefix: 'ml' },
+  top: { prefix: 'top' },
+  right: { prefix: 'right' },
+  bottom: { prefix: 'bottom' },
+  left: { prefix: 'left' },
+  borderRadius: { prefix: 'rounded' },
+  borderTopLeftRadius: { prefix: 'rounded-tl' },
+  borderTopRightRadius: { prefix: 'rounded-tr' },
+  borderBottomLeftRadius: { prefix: 'rounded-bl' },
+  borderBottomRightRadius: { prefix: 'rounded-br' },
+  gap: { prefix: 'gap' },
+  fontWeight: { prefix: 'font' },
+  lineHeight: { prefix: 'leading' },
+  letterSpacing: { prefix: 'tracking' },
+  flexBasis: { prefix: 'basis' },
+  opacity: { prefix: 'opacity' },
+  zIndex: { prefix: 'z' },
+  boxShadow: { prefix: 'shadow' },
+};
+
+const sanitizeClass = (s: string): string => s.replace(/\s+/g, '_');
+
+/** Encode a CSS prop:value as a lossless Tailwind-style utility class. */
+export function cssToUtilityClass(prop: string, value: string | number): string {
+  const v = String(value);
+  if (ENUM_UTILITIES[prop]?.[v]) return ENUM_UTILITIES[prop][v] as string;
+  const arb = ARB_MAP[prop];
+  if (!arb) return `[${sanitizeClass(prop)}:${sanitizeClass(v)}]`; // arbitrary property — lossless
+  const val = typeof value === 'number' ? `${value}px` : v;
+  const inner = arb.hint ? `${arb.hint}:${sanitizeClass(val)}` : sanitizeClass(val);
+  return `${arb.prefix}-[${inner}]`;
+}
+
+/** The dedupe group of an existing utility class (so a re-set replaces same-property classes). */
+function classGroup(cls: string): string {
+  if (ENUM_GROUP[cls]) return ENUM_GROUP[cls];
+  const arb =
+    cls.indexOf('-[') >= 0 ? cls.slice(0, cls.indexOf('-[') + 2) : cls.startsWith('[') ? '[' : '';
+  if (!arb) return cls;
+  // include a type hint (color:/length:) in the group so text-[color:..] != text-[length:..]
+  const hintMatch = cls.match(/\[(color|length):/);
+  return hintMatch ? `${arb}${hintMatch[1]}:` : arb;
+}
+
+/**
+ * Merge a class into the element's `className="..."` literal, or add the
+ * attribute.
+ *
+ * D-A1 assessment (wave 13, `docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md`): unlike
+ * `setInlineStyle`, this function has NO distinguishable append-vs-replace
+ * branch to surface as `appended` — it always does the SAME operation (filter
+ * out any class in the target's dedupe GROUP, then push the new class),
+ * regardless of whether a same-group class existed before. Scoped OUT of this
+ * wave's fix: see the design doc's SHIPPED note for why the className route's
+ * undo correctness is a separate, broader pre-existing gap, not this bug.
+ */
+export function setClassName(code: string, elementStart: number, cls: string): StyleEditResult {
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return { code, changed: false, dynamic: false };
+  const openSeg = code.slice(elementStart, tagEnd);
+  const m = openSeg.match(/className\s*=\s*"([^"]*)"/);
+  if (m && m.index != null) {
+    // dedupe by PROPERTY GROUP (not raw prefix) so re-setting any prop replaces its
+    // prior class — incl. color-vs-fontSize (both `text-`) and enum/arbitrary-prop.
+    const group = classGroup(cls);
+    const existing = (m[1] ?? '')
+      .split(/\s+/)
+      .filter((c) => c && c !== cls && classGroup(c) !== group);
+    const merged = [...existing, cls].join(' ').trim();
+    const valStart = elementStart + (m.index ?? 0) + m[0].indexOf('"') + 1;
+    const valEnd = valStart + (m[1]?.length ?? 0);
+    return {
+      code: `${code.slice(0, valStart)}${merged}${code.slice(valEnd)}`,
+      changed: true,
+      dynamic: false,
+    };
+  }
+  if (/className\s*=\s*\{/.test(openSeg)) return { code, changed: false, dynamic: true }; // dynamic className
+  const selfClose = code[tagEnd - 1] === '/';
+  const insertAt = selfClose ? tagEnd - 1 : tagEnd;
+  return {
+    code: `${code.slice(0, insertAt)} className="${cls}"${code.slice(insertAt)}`,
+    changed: true,
+    dynamic: false,
+  };
+}
+
+/**
+ * Route a style edit to the right target (F5): if the element has a literal
+ * `className`, write a (lossless) utility class; otherwise write inline style.
+ */
+export function writeStyleAuto(
+  code: string,
+  elementStart: number,
+  prop: string,
+  value: string | number,
+): StyleEditResult & { route: 'class' | 'inline' } {
+  const tagEnd = findTagEnd(code, elementStart);
+  const openSeg = tagEnd > 0 ? code.slice(elementStart, tagEnd) : '';
+  if (/className\s*=\s*"/.test(openSeg)) {
+    return { ...setClassName(code, elementStart, cssToUtilityClass(prop, value)), route: 'class' };
+  }
+  return { ...setInlineStyle(code, elementStart, prop, value), route: 'inline' };
+}
+
+// --- Cap 2: CSS-file editing (visual-edit writer.ts surgicalCssEdit :1109) ---
+
+/** camelCase CSS prop -> kebab-case, for matching a declaration in a CSS rule body. */
+function cssCamelToKebab(s: string): string {
+  return s.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/** Find a standalone occurrence of `selectorText` in CSS source (not a substring of a
+ *  longer selector). Returns the index or -1. */
+function findSelectorIndex(cssSource: string, selectorText: string): number {
+  let searchFrom = 0;
+  while (searchFrom < cssSource.length) {
+    const idx = cssSource.indexOf(selectorText, searchFrom);
+    if (idx === -1) break;
+    const before = idx > 0 ? cssSource[idx - 1] : '\n';
+    if (idx === 0 || /[\s\n{},;]/.test(before ?? '')) {
+      const after = cssSource[idx + selectorText.length];
+      if (after === '{' || after === ' ' || after === '\n' || after === '\r' || after === '\t') {
+        return idx;
+      }
+    }
+    searchFrom = idx + 1;
+  }
+  return -1;
+}
+
+/** The `{ … }` body range of the rule whose selector starts at `selectorIdx`, or null. */
+function findRuleBody(
+  cssSource: string,
+  selectorIdx: number,
+  selectorText: string,
+): { bodyStart: number; bodyEnd: number } | null {
+  let i = selectorIdx + selectorText.length;
+  while (i < cssSource.length && cssSource[i] !== '{') i++;
+  if (i >= cssSource.length) return null;
+  const bodyStart = i + 1;
+  let depth = 1;
+  i++;
+  while (i < cssSource.length && depth > 0) {
+    if (cssSource[i] === '{') depth++;
+    else if (cssSource[i] === '}') depth--;
+    if (depth > 0) i++;
+  }
+  return { bodyStart, bodyEnd: i };
+}
+
+/**
+ * Surgically replace (or append) a property value inside a CSS RULE BODY, editing the
+ * source in place and preserving all other declarations/formatting (visual-edit
+ * `surgicalCssEdit` :1109). Returns the edited source, or `null` when the selector is not
+ * present in the file (i.e. it's GENERATED CSS — a Tailwind utility, styled-components —
+ * that must not be hand-edited; the caller falls back to class/inline routing).
+ */
+export function surgicalCssEdit(
+  cssSource: string,
+  selectorText: string,
+  propName: string,
+  newValue: string,
+): string | null {
+  const selectorIdx = findSelectorIndex(cssSource, selectorText);
+  if (selectorIdx === -1) return null;
+  const rng = findRuleBody(cssSource, selectorIdx, selectorText);
+  if (!rng) return null;
+  const { bodyStart, bodyEnd } = rng;
+  const body = cssSource.slice(bodyStart, bodyEnd);
+
+  const kebabProp = cssCamelToKebab(propName);
+  const escaped = kebabProp.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const propRegex = new RegExp(`(^|[;\\n\\s])\\s*(${escaped})\\s*:`, 'm');
+  const match = propRegex.exec(body);
+
+  if (match) {
+    const matchStart = bodyStart + match.index + match[0].length; // right after the ':'
+    let valEnd = matchStart;
+    while (valEnd < bodyEnd && cssSource[valEnd] !== ';' && cssSource[valEnd] !== '}') valEnd++;
+    return `${cssSource.slice(0, matchStart)} ${newValue}${cssSource.slice(valEnd)}`;
+  }
+
+  // Property absent — append it before the closing '}', matching existing indentation.
+  let indent = '  ';
+  for (const line of body.split('\n')) {
+    if (line.trim().includes(':')) {
+      indent = line.match(/^(\s*)/)?.[1] ?? indent;
+      break;
+    }
+  }
+  const trimmed = body.trimEnd();
+  const needsSemi = trimmed.length > 0 && !trimmed.endsWith(';');
+  const insertion = `${needsSemi ? ';\n' : '\n'}${indent}${kebabProp}: ${newValue};\n`;
+  return cssSource.slice(0, bodyEnd) + insertion + cssSource.slice(bodyEnd);
+}
+
+/** A matched CSS rule as produced by `inspect.ts`'s `getMatchedCssRules` — the subset the
+ *  CSS write path needs. */
+export interface CssRuleTarget {
+  selectorText: string;
+  sourceFile: string;
+  properties: Record<string, string>;
+}
+
+/**
+ * Pick the target rule for a property write: the LAST matched rule that declares the
+ * property (cascade — last declaration wins), mirroring visual-edit `writeCssRuleChange`
+ * :1198. Returns the rule + the prior value (for the undo inverse), or null when no
+ * matched rule declares the property (⇒ caller routes to class/inline instead).
+ */
+export function pickCssRuleTarget(
+  matchedRules: readonly CssRuleTarget[],
+  prop: string,
+): { rule: CssRuleTarget; prevValue: string } | null {
+  const kebabProp = cssCamelToKebab(prop);
+  let target: CssRuleTarget | null = null;
+  for (const rule of matchedRules) {
+    if (kebabProp in rule.properties) target = rule;
+  }
+  if (!target) return null;
+  return { rule: target, prevValue: target.properties[kebabProp] ?? '' };
+}
+
+// --- Cap 3: text-content editing (visual-edit writer.ts getEditableText :817 /
+//     editTextContent :861) ---
+
+/** The `<`-relative content range (between the opening tag's `>` and the closing `</`)
+ *  of the element at `elementStart`, plus whether it is a pure-text (editable) body. */
+function findTextContentRange(
+  code: string,
+  elementStart: number,
+): { contentStart: number; closingTagStart: number; content: string } | null {
+  if (code[elementStart] !== '<') return null;
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0 || code[tagEnd - 1] === '/') return null; // self-closing ⇒ no text body
+  const contentStart = tagEnd + 1;
+  const elementEnd = findElementEnd(code, elementStart);
+  if (elementEnd < 0) return null;
+  // The closing tag is the last `</` before elementEnd.
+  let closingTagStart = elementEnd - 1;
+  while (
+    closingTagStart > contentStart &&
+    !(code[closingTagStart] === '<' && code[closingTagStart + 1] === '/')
+  ) {
+    closingTagStart--;
+  }
+  return { contentStart, closingTagStart, content: code.slice(contentStart, closingTagStart) };
+}
+
+/**
+ * Return an element's editable text — its content trimmed — IFF the body is pure text (no
+ * `{expression}` and no child `<element>`); else null (visual-edit `getEditableText` :817).
+ * This is the double-click-to-edit gate: only a leaf text node is editable in place.
+ */
+export function getEditableText(code: string, elementStart: number): string | null {
+  const rng = findTextContentRange(code, elementStart);
+  if (!rng) return null;
+  if (rng.content.includes('{') || rng.content.includes('<')) return null; // dynamic/children
+  const trimmed = rng.content.trim();
+  return trimmed ? trimmed : null;
+}
+
+/** Escape the JSX-structural characters so replacement text can't break the source tree
+ *  (`<`/`{`/`}` become entities; `&` first so we don't double-encode). */
+function escapeJsxText(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/\{/g, '&#123;')
+    .replace(/\}/g, '&#125;');
+}
+
+/**
+ * Replace an element's text content in place, preserving the surrounding whitespace
+ * (only the trimmed text portion is swapped — visual-edit `editTextContent` :861). Refuses
+ * (guard) when the body is not pure text (`dynamic: true`), exactly like the read gate.
+ */
+export function editTextContent(
+  code: string,
+  elementStart: number,
+  newText: string,
+): StyleEditResult {
+  const rng = findTextContentRange(code, elementStart);
+  if (!rng) return { code, changed: false, dynamic: false };
+  const { contentStart, closingTagStart, content } = rng;
+  if (content.includes('{') || content.includes('<'))
+    return { code, changed: false, dynamic: true };
+  const leading = content.length - content.trimStart().length;
+  const trailing = content.length - content.trimEnd().length;
+  const replaceStart = contentStart + leading;
+  const replaceEnd = closingTagStart - trailing;
+  const next = code.slice(0, replaceStart) + escapeJsxText(newText) + code.slice(replaceEnd);
+  return { code: next, changed: next !== code, dynamic: false };
+}
+
+// --- Cap 4: JSX prop / attribute editing (visual-edit writer.ts analyzeJsxAttributes
+//     :913 / writePropChange :1018 / fetchPropAnalysis :1069) ---
+
+export interface JsxAttrInfo {
+  name: string;
+  /** Value char range in `code` (exclusive of quotes/braces). -1 for a boolean shorthand. */
+  valueStart: number;
+  valueEnd: number;
+  rawValue: string;
+  /** True if the value is a `{…}` expression container (vs a `"…"` string). */
+  isExpression: boolean;
+  /** True if the value is a literal we can safely rewrite (string, number, boolean). */
+  isLiteral: boolean;
+}
+
+/** Skip a `{…}` region (spread or expression), respecting nested braces + strings. Returns
+ *  the index just past the matching `}`. */
+function skipBraces(code: string, from: number): number {
+  let i = from + 1;
+  let depth = 1;
+  let inStr: string | null = null;
+  while (i < code.length && depth > 0) {
+    const ch = code[i];
+    if (inStr) {
+      if (ch === inStr && code[i - 1] !== '\\') inStr = null;
+    } else if (ch === "'" || ch === '"' || ch === '`') inStr = ch;
+    else if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    i++;
+  }
+  return i;
+}
+
+/** Read a quoted string value starting at the opening quote; returns [valueStart, valueEnd,
+ *  indexAfterClosingQuote]. */
+function readQuotedValue(code: string, openQuote: number, delim: string): [number, number, number] {
+  let i = openQuote + 1;
+  const valueStart = i;
+  while (i < code.length && code[i] !== delim) {
+    if (code[i] === '\\') i++;
+    i++;
+  }
+  return [valueStart, i, i + 1];
+}
+
+const LITERAL_EXPR_RE = /^(\d+(\.\d+)?|true|false|'[^']*'|"[^"]*")$/;
+
+/**
+ * Parse the attributes of a JSX opening tag `<Tag …>` (visual-edit `analyzeJsxAttributes`
+ * :913). Handles string values, `{expression}` values (literal detection), boolean
+ * shorthand, and `{...spread}` (skipped). Pure string scan — no parser.
+ */
+export function analyzeJsxAttributes(
+  code: string,
+  tagStart: number,
+  tagEnd: number,
+): JsxAttrInfo[] {
+  const attrs: JsxAttrInfo[] = [];
+  const skipWs = (i: number): number => {
+    while (i <= tagEnd && /\s/.test(code[i] ?? '')) i++;
+    return i;
+  };
+  let i = tagStart + 1; // skip '<'
+  while (i <= tagEnd && !/[\s>/]/.test(code[i] ?? '>')) i++; // skip tag name
+
+  while (i <= tagEnd) {
+    i = skipWs(i);
+    if (i > tagEnd || code[i] === '>' || (code[i] === '/' && code[i + 1] === '>')) break;
+    if (code[i] === '{') {
+      i = skipBraces(code, i); // {...spread}
+      continue;
+    }
+    const nameStart = i;
+    while (i <= tagEnd && /[\w-]/.test(code[i] ?? '')) i++;
+    const name = code.slice(nameStart, i);
+    if (!name) {
+      i++;
+      continue;
+    }
+    i = skipWs(i);
+    if (code[i] !== '=') {
+      attrs.push(booleanShorthand(name)); // e.g. `disabled`
+      continue;
+    }
+    i = skipWs(i + 1); // skip '=' + whitespace
+    const parsed = readAttrValue(code, i);
+    if (!parsed) {
+      i++;
+      continue;
+    }
+    attrs.push(makeAttr(code, name, parsed));
+    i = parsed.next;
+  }
+  return attrs;
+}
+
+/** A boolean-shorthand attribute descriptor (`disabled` ⇒ `true`, no value range). */
+function booleanShorthand(name: string): JsxAttrInfo {
+  return {
+    name,
+    valueStart: -1,
+    valueEnd: -1,
+    rawValue: 'true',
+    isExpression: false,
+    isLiteral: true,
+  };
+}
+
+/** Read an attribute value starting at `i` (the delimiter after `=`). Returns the value
+ *  range + whether it's an expression + the index past it, or null for an unrecognized
+ *  delimiter (the caller advances one char). */
+function readAttrValue(
+  code: string,
+  i: number,
+): { valueStart: number; valueEnd: number; isExpression: boolean; next: number } | null {
+  const delim = code[i];
+  if (delim === '"' || delim === "'") {
+    const [valueStart, valueEnd, next] = readQuotedValue(code, i, delim);
+    return { valueStart, valueEnd, isExpression: false, next };
+  }
+  if (delim === '{') {
+    const valueEnd = skipBraces(code, i) - 1;
+    return { valueStart: i + 1, valueEnd, isExpression: true, next: valueEnd + 1 };
+  }
+  return null;
+}
+
+/** Build a `JsxAttrInfo` from a parsed value range (computes rawValue + literal flag). */
+function makeAttr(
+  code: string,
+  name: string,
+  parsed: { valueStart: number; valueEnd: number; isExpression: boolean },
+): JsxAttrInfo {
+  const rawValue = code.slice(parsed.valueStart, parsed.valueEnd).trim();
+  const isLiteral = !parsed.isExpression || LITERAL_EXPR_RE.test(rawValue);
+  return {
+    name,
+    valueStart: parsed.valueStart,
+    valueEnd: parsed.valueEnd,
+    rawValue,
+    isExpression: parsed.isExpression,
+    isLiteral,
+  };
+}
+
+/** Props never surfaced as editable component props (visual-edit `fetchPropAnalysis` skip
+ *  set + on* handlers — event handlers are always dynamic). */
+const PROP_SKIP = new Set(['key', 'ref', 'data-oid', 'style', 'className', 'children']);
+const isSkippedProp = (name: string): boolean => PROP_SKIP.has(name) || /^on[A-Z]/.test(name);
+
+/** Split a component's JSX attributes into editable (literal) vs dynamic (expression) —
+ *  the Props inspector uses this to gate which props can be written (visual-edit
+ *  `fetchPropAnalysis` :1069). */
+export function analyzeProps(
+  code: string,
+  elementStart: number,
+): { editable: string[]; dynamic: string[] } {
+  const empty = { editable: [], dynamic: [] };
+  if (code[elementStart] !== '<') return empty;
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return empty;
+  const editable: string[] = [];
+  const dynamic: string[] = [];
+  for (const attr of analyzeJsxAttributes(code, elementStart, tagEnd)) {
+    if (isSkippedProp(attr.name)) continue;
+    (attr.isLiteral ? editable : dynamic).push(attr.name);
+  }
+  return { editable, dynamic };
+}
+
+/** Format the replacement for a prop write, matching the original value's shape (number/
+ *  boolean/quoted expression, or a plain string attribute). */
+function formatPropReplacement(attr: JsxAttrInfo, newValue: string): string {
+  if (!attr.isExpression) return newValue; // string attribute — content between the quotes
+  const raw = attr.rawValue;
+  if (/^\d+(\.\d+)?$/.test(raw)) {
+    const num = Number(newValue);
+    return Number.isNaN(num) ? `'${newValue}'` : String(num);
+  }
+  if (raw === 'true' || raw === 'false') {
+    return newValue === 'true' || newValue === 'false' ? newValue : `'${newValue}'`;
+  }
+  if (/^"[^"]*"$/.test(raw)) return `"${newValue.replace(/"/g, '\\"')}"`;
+  return `'${newValue.replace(/'/g, "\\'")}'`;
+}
+
+/**
+ * Write a component prop change back to source at the call site (visual-edit
+ * `writePropChange` :1018). Refuses (guards) a dynamic (non-literal) prop and skips the
+ * event-handler / structural props. `elementStart` is the call-site element's `<`.
+ */
+export function writePropChange(
+  code: string,
+  elementStart: number,
+  propName: string,
+  newValue: string,
+): StyleEditResult {
+  if (code[elementStart] !== '<') return { code, changed: false, dynamic: false };
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return { code, changed: false, dynamic: false };
+  if (isSkippedProp(propName)) return { code, changed: false, dynamic: false };
+  const attr = analyzeJsxAttributes(code, elementStart, tagEnd).find((a) => a.name === propName);
+  if (!attr) return { code, changed: false, dynamic: false };
+  if (!attr.isLiteral || attr.valueStart < 0) return { code, changed: false, dynamic: true };
+  const replacement = formatPropReplacement(attr, newValue);
+  const next = code.slice(0, attr.valueStart) + replacement + code.slice(attr.valueEnd);
+  return { code: next, changed: next !== code, dynamic: false };
+}
+
+// --- Cap 5: source structural ops (visual-edit writer.ts reorderChild :483 /
+//     duplicateElement :559 / wrapElement :634 / unwrapElement :679 /
+//     reparentElement :743) ---
+
+export interface StructEditResult {
+  code: string;
+  changed: boolean;
+}
+
+/** Expand a JSX element at `elementStart` to its full LINE block (leading whitespace on the
+ *  first line, trailing newline on the last) — the unit these line-based ops move/copy. */
+function lineBlockRange(
+  code: string,
+  elementStart: number,
+): { lineStart: number; lineEnd: number } | null {
+  if (code[elementStart] !== '<') return null;
+  const end = findElementEnd(code, elementStart);
+  if (end < 0) return null;
+  let lineStart = elementStart;
+  while (lineStart > 0 && code[lineStart - 1] !== '\n') lineStart--;
+  let lineEnd = end;
+  while (lineEnd < code.length && code[lineEnd] !== '\n') lineEnd++;
+  if (lineEnd < code.length && code[lineEnd] === '\n') lineEnd++;
+  return { lineStart, lineEnd };
+}
+
+/** The `<` of a parent's closing tag, given the parent's opening `<` (visual-edit's
+ *  backwards scan from the element end). */
+function closingTagStartOf(code: string, parentStart: number): number | null {
+  const parentEnd = findElementEnd(code, parentStart);
+  if (parentEnd < 0) return null;
+  let i = parentEnd;
+  while (i > parentStart && code[i - 1] !== '<') i--;
+  return i - 1; // point at the '<'
+}
+
+/** Duplicate the element's line block, inserting the copy immediately after it (visual-edit
+ *  `duplicateElement` :559). */
+export function duplicateElement(code: string, elementStart: number): StructEditResult {
+  const r = lineBlockRange(code, elementStart);
+  if (!r) return { code, changed: false };
+  const block = code.slice(r.lineStart, r.lineEnd);
+  return { code: code.slice(0, r.lineEnd) + block + code.slice(r.lineEnd), changed: true };
+}
+
+/** Wrap the element in a new `<wrapperTag>…</wrapperTag>` container, re-indenting the
+ *  wrapped block one level (visual-edit `wrapElement` :634). */
+export function wrapElement(
+  code: string,
+  elementStart: number,
+  wrapperTag = 'div',
+): StructEditResult {
+  const r = lineBlockRange(code, elementStart);
+  if (!r) return { code, changed: false };
+  const block = code.slice(r.lineStart, r.lineEnd);
+  const indent = block.match(/^(\s*)/)?.[1] ?? '';
+  const reindented = block
+    .split('\n')
+    .map((line) => (line.length > 0 ? `  ${line}` : line))
+    .join('\n');
+  const wrapper = `${indent}<${wrapperTag}>\n${reindented}${indent}</${wrapperTag}>\n`;
+  return { code: code.slice(0, r.lineStart) + wrapper + code.slice(r.lineEnd), changed: true };
+}
+
+/** Unwrap the element — replace it with its children, dedented one level (visual-edit
+ *  `unwrapElement` :679). A self-closing element simply deletes. */
+export function unwrapElement(code: string, elementStart: number): StructEditResult {
+  if (code[elementStart] !== '<') return { code, changed: false };
+  const end = findElementEnd(code, elementStart);
+  const openTagEnd = findTagEnd(code, elementStart);
+  if (end < 0 || openTagEnd < 0) return { code, changed: false };
+  if (code[openTagEnd - 1] === '/') return deleteElement(code, elementStart); // self-closing
+  let closingTagStart = end;
+  while (closingTagStart > elementStart && code[closingTagStart - 1] !== '<') closingTagStart--;
+  closingTagStart--; // point at '<'
+  const children = code.slice(openTagEnd + 1, closingTagStart);
+  const r = lineBlockRange(code, elementStart);
+  if (!r) return { code, changed: false };
+  const dedented = children
+    .split('\n')
+    .map((line) =>
+      line.startsWith('  ') ? line.slice(2) : line.startsWith('\t') ? line.slice(1) : line,
+    )
+    .join('\n');
+  return { code: code.slice(0, r.lineStart) + dedented + code.slice(r.lineEnd), changed: true };
+}
+
+/** Insert a new child element `<tag />` just before `parentStart`'s closing tag, indented
+ *  to match the parent's children (the "create" primitive). */
+export function insertChildElement(
+  code: string,
+  parentStart: number,
+  tag = 'div',
+): StructEditResult {
+  const closingTagStart = closingTagStartOf(code, parentStart);
+  if (closingTagStart == null) return { code, changed: false };
+  let parentLineStart = parentStart;
+  while (parentLineStart > 0 && code[parentLineStart - 1] !== '\n') parentLineStart--;
+  const parentIndent = code.slice(parentLineStart, parentStart).match(/^(\s*)/)?.[1] ?? '';
+  let insertPos = closingTagStart;
+  while (insertPos > 0 && code[insertPos - 1] !== '\n') insertPos--;
+  const child = `${parentIndent}  <${tag} />\n`;
+  return { code: code.slice(0, insertPos) + child + code.slice(insertPos), changed: true };
+}
+
+/** Reorder the element among its siblings: before `beforeStart` (an OID-resolved sibling
+ *  offset), or — when `beforeStart` is null — at the end of `parentStart` (visual-edit
+ *  `reorderChild` :483). OID-resolved offsets, immune to index races. */
+export function reorderChild(
+  code: string,
+  elementStart: number,
+  beforeStart: number | null,
+  parentStart: number | null,
+): StructEditResult {
+  const r = lineBlockRange(code, elementStart);
+  if (!r) return { code, changed: false };
+  const { lineStart, lineEnd } = r;
+  const block = code.slice(lineStart, lineEnd);
+  const removedLength = lineEnd - lineStart;
+
+  let targetLineStart: number;
+  if (beforeStart != null) {
+    targetLineStart = beforeStart;
+    while (targetLineStart > 0 && code[targetLineStart - 1] !== '\n') targetLineStart--;
+    if (targetLineStart === lineStart) return { code, changed: false }; // same position
+  } else if (parentStart != null) {
+    const closingTagStart = closingTagStartOf(code, parentStart);
+    if (closingTagStart == null) return { code, changed: false };
+    targetLineStart = closingTagStart;
+    while (targetLineStart > 0 && code[targetLineStart - 1] !== '\n') targetLineStart--;
+    if (lineStart >= targetLineStart) return { code, changed: false }; // already at end
+  } else {
+    return { code, changed: false };
+  }
+
+  const without = code.slice(0, lineStart) + code.slice(lineEnd);
+  const adj = targetLineStart > lineStart ? targetLineStart - removedLength : targetLineStart;
+  return { code: without.slice(0, adj) + block + without.slice(adj), changed: true };
+}
+
+/** Reparent the element to be the last child of `parentStart`, re-indented to the parent's
+ *  child level (visual-edit `reparentElement` :743). Same-file only (the caller guards). */
+export function reparentElement(
+  code: string,
+  elementStart: number,
+  parentStart: number,
+): StructEditResult {
+  const r = lineBlockRange(code, elementStart);
+  if (!r) return { code, changed: false };
+  const { lineStart: elLineStart, lineEnd: elLineEnd } = r;
+  const block = code.slice(elLineStart, elLineEnd);
+  const closingTagStart = closingTagStartOf(code, parentStart);
+  if (closingTagStart == null) return { code, changed: false };
+
+  let parentLineStart = parentStart;
+  while (parentLineStart > 0 && code[parentLineStart - 1] !== '\n') parentLineStart--;
+  const parentIndent = code.slice(parentLineStart, parentStart).match(/^(\s*)/)?.[1] ?? '';
+  const childIndent = `${parentIndent}  `;
+  const reindented = block
+    .split('\n')
+    .map((line) => {
+      const trimmed = line.replace(/^\s*/, '');
+      return trimmed ? childIndent + trimmed : '';
+    })
+    .join('\n');
+
+  const without = code.slice(0, elLineStart) + code.slice(elLineEnd);
+  let adjustedClosing = closingTagStart;
+  if (elLineStart < closingTagStart) adjustedClosing -= elLineEnd - elLineStart;
+  let insertPos = adjustedClosing;
+  while (insertPos > 0 && without[insertPos - 1] !== '\n') insertPos--;
+  return {
+    code: without.slice(0, insertPos) + reindented + without.slice(insertPos),
+    changed: true,
+  };
+}
+
+/** Delete the element starting at `elementStart` from source (C8). */
+export function deleteElement(
+  code: string,
+  elementStart: number,
+): { code: string; changed: boolean } {
+  const end = findElementEnd(code, elementStart);
+  if (end < 0) return { code, changed: false };
+  // also consume leading whitespace on the line + trailing newline
+  let s = elementStart;
+  while (s > 0 && (code[s - 1] === ' ' || code[s - 1] === '\t')) s--;
+  let e = end;
+  if (code[e] === '\n') e++;
+  return { code: code.slice(0, s) + code.slice(e), changed: true };
+}
+
+/**
+ * Delete MULTIPLE elements from a SINGLE `code` snapshot, given every target's
+ * `elementStart` offset resolved against that SAME snapshot (delete-order-residual
+ * fix — `vite-plugin-ui-oid.ts`'s `handleStructMany`). Sound and caller-order-
+ * independent: every offset is resolved from the file ONCE, up front, then applied
+ * highest-offset-first — each `deleteElement` call only ever removes text AT OR
+ * AFTER its own target, so every offset still queued (all of them numerically
+ * SMALLER, since we process descending) is untouched by it and stays valid. A
+ * nested descendant's `elementStart` is always numerically greater than its
+ * ancestor's (it appears later in source), so this single offset-value rule also
+ * deletes a selected descendant before a selected ancestor, with no separate
+ * ancestor/descendant case to reason about. Unlike re-resolving each target by
+ * re-scanning/re-transforming the file between deletes, this never recomputes an
+ * OID's identity mid-batch — it only ever reads the ALREADY-RESOLVED offsets handed
+ * to it, so it cannot suffer the occurrence-index churn a live re-transform would
+ * introduce (deleting one same-tag sibling shifts every later sibling's own
+ * `component:tag:nthOccurrence` signature, which would silently relabel it as a
+ * DIFFERENT, already-used oid if resolution were re-derived from a fresh transform
+ * mid-batch — the reason `handleStruct`'s per-call resolution is not simply looped
+ * here without change).
+ */
+export function deleteElements(
+  code: string,
+  elementStarts: readonly number[],
+): { code: string; changed: boolean } {
+  const sorted = [...elementStarts].sort((a, b) => b - a); // highest offset first
+  let cur = code;
+  let changed = false;
+  for (const off of sorted) {
+    const result = deleteElement(cur, off);
+    if (result.changed) {
+      cur = result.code;
+      changed = true;
+    }
+  }
+  return { code: cur, changed };
+}