@volter/editor-react 0.5.211 → 0.5.212

package/src/source/writer.ts

@@ -1,11 +1,5 @@
-/**
- * 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).
- */
+/** Surgical source edits by element offset. Preserve unrelated properties,
+ * formatting, and comments, and refuse writes to expression-bound values. */
 
 import { UTILITY_CLASSES_UNPROVEN, type UtilityClassSupport } from './utility-class-support';
 
@@ -19,15 +13,8 @@ export interface StyleProperty {
   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.
-   */
+  /** Start of the key/value span, excluding surrounding whitespace. */
   memberStart: number;
-  memberEnd: number;
 }
 
 /** Find the `>` that closes the opening tag starting at `start` (a `<`). */
@@ -40,12 +27,7 @@ export function findTagEnd(code: string, start: number): number {
       if (c === str && code[i - 1] !== '\\') str = null;
       continue;
     }
-    // A COMMENT. JSX allows one between attributes and inside an attribute's
-    // `{…}` expression alike, and an apostrophe in its prose ("the tab's drag
-    // handle", "the palette's active ink") otherwise opens a string that
-    // swallows the tag's own `>` and every element after it — measured on
-    // `GameHierarchy.tsx` and its neighbours. A self-closing `/` is
-    // followed by `>`, never by `/` or `*`, so it cannot be mistaken for one.
+    // Skip comments between attributes or inside expressions before interpreting quotes.
     if (c === '/' && code[i + 1] === '/') {
       const newline = code.indexOf('\n', i);
       if (newline < 0) return -1;
@@ -130,7 +112,6 @@ export function analyzeStyleProperties(objBody: string, baseOffset: number): Sty
           valueStart,
           valueEnd,
           memberStart: baseOffset + keyStart,
-          memberEnd: valueEnd,
         });
       }
     }
@@ -165,28 +146,7 @@ export interface StyleEditResult {
   changed: boolean;
   /** True if the edit was refused because the existing value is a JS expression. */
   dynamic: boolean;
-  /**
-   * D-A1: 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;
-  /**
-   * Refused because the property's existing value is a CSS CUSTOM-PROPERTY
-   * REFERENCE — `backgroundColor: 'var(--brand-color)'`. Carries the reference
-   * text so the refusal can name the token the author would otherwise have lost.
-   *
-   * A `var()` is a literal string, so the dynamic-expression guard above never
-   * saw it: an ordinary colour-picker commit rewrote a design-token binding to
-   * `#ff0000`, silently, on one click. Guarding it is the same idiom for the
-   * same reason — the source value is a REFERENCE, and replacing it with a
-   * literal is a loss no widget can compose back.
-   */
+  /** CSS custom-property reference guarded against replacement by a literal. */
   tokenRef?: string;
 }
 
@@ -257,7 +217,7 @@ export function setInlineStyle(
     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 };
+    return { code: next, changed: true, dynamic: false };
   }
 
   // A whole-attribute dynamic style (`style={expr}`, single brace) exists but is
@@ -274,20 +234,9 @@ export function setInlineStyle(
   return { code: next, changed: true, dynamic: false };
 }
 
-/**
- * D-A2: 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).
- */
+/** Remove a literal inline-style property and repair adjacent separators.
+ * An absent or dynamic member is unchanged; removing the only member leaves
+ * an empty style object for subsequent writes. */
 export function removeInlineStyle(
   code: string,
   elementStart: number,
@@ -307,7 +256,7 @@ export function removeInlineStyle(
   // 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;
+  let after = existing.valueEnd;
   while (after < styleObj.innerEnd && /\s/.test(code[after] ?? '')) after++;
   if (code[after] === ',') {
     let end = after + 1;
@@ -323,7 +272,7 @@ export function removeInlineStyle(
   while (before >= styleObj.innerStart && /\s/.test(code[before] ?? '')) before--;
   if (code[before] === ',') {
     return {
-      code: code.slice(0, before) + code.slice(existing.memberEnd),
+      code: code.slice(0, before) + code.slice(existing.valueEnd),
       changed: true,
       dynamic: false,
     };
@@ -376,7 +325,7 @@ function skipJsxExpression(code: string, open: number): number {
       if (depth === 0) return i;
       continue;
     }
-    // NESTED JSX — `{cond ? <div>the shot's takes</div> : null}`. Inside the
+    // NESTED JSX — `{cond ? <div>the shot's takes</div>: null}`. Inside the
     // element the quotes are TEXT again, so the element is handed back to
     // `findElementEnd`, whose walk knows that; scanning it here would read
     // that apostrophe as a string exactly like the defect this pair fixes.
@@ -412,30 +361,9 @@ function startsTag(code: string, i: number): boolean {
   );
 }
 
-/**
- * Find the end (exclusive) of a full JSX element starting at `<Tag` — balancing
- * nested same-tag elements and skipping `{…}` expressions whole (C8).
- *
- * **A QUOTE BETWEEN TWO TAGS IS TEXT, NOT A STRING**, and reading it as one
- * destroyed source. This walk used to flip into "inside a string" on any `'`,
- * `"` or backtick it met, exactly as {@link findTagEnd} does INSIDE a tag —
- * but between tags those characters are JSX children, and an apostrophe is an
- * ordinary English one. Measured 2026-09-19 on the game template's own
- * `MainScene.tsx`: the JSX comment inside `<group name="Light Rig">` says
- * *"The sun's position… that component's header… than this scene's."* — three
- * apostrophes, so the walk was left mid-"string", never saw `</group>`, and
- * answered with the END OF THE FILE. Every consumer of that answer takes the
- * whole rest of the component: Delete on the Light Rig row would have removed
- * it, copy would have copied it, and `group` wrote a structurally broken file
- * (that is how this was found).
- *
- * So: enter a string only inside a `{…}` expression container, where
- * {@link skipJsxExpression} also handles `//` and block comments — which is
- * what makes a JSX comment's prose invisible to this walk — and step over any
- * OTHER element's opening tag with {@link findTagEnd}, so its attributes'
- * quotes and braces never reach here either. Only our own tag moves `depth`,
- * so another element's children stay in this walk and cost nothing.
- */
+/** Find a JSX element's exclusive end, balancing same-tag nesting. Quotes
+ * between tags are text; expression containers and other opening tags are
+ * skipped with their own comment and string rules. */
 export function findElementEnd(code: string, start: number): number {
   const tagEnd = findTagEnd(code, start);
   if (tagEnd < 0) return -1;
@@ -465,7 +393,7 @@ export function findElementEnd(code: string, start: number): number {
     }
     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
+      // 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) {
@@ -486,17 +414,7 @@ export function findElementEnd(code: string, start: number): number {
   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.
- */
-// 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.
+// --- Style routing: inline declarations and className utilities ---
 const ENUM_UTILITIES: Record<string, Record<string, string>> = {
   display: {
     flex: 'flex',
@@ -588,7 +506,7 @@ const ENUM_GROUP: Record<string, string> = (() => {
 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).
+  // hints to stay unambiguous for property-based dedupe.
   borderColor: { prefix: 'border', hint: 'color' },
   borderWidth: { prefix: 'border', hint: 'length' },
   color: { prefix: 'text', hint: 'color' },
@@ -652,18 +570,8 @@ function classGroup(cls: string): string {
   return hintMatch ? `${arb}${hintMatch[1]}:` : arb;
 }
 
-/**
- * Merge a class into the element's `className="..."` literal, or add the
- * attribute.
- *
- * D-A1 assessment: 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.
- */
+/** Merge a utility class into a literal className, replacing classes from
+ * the same deduplication group, or add the attribute when absent. */
 export function setClassName(code: string, elementStart: number, cls: string): StyleEditResult {
   const tagEnd = findTagEnd(code, elementStart);
   if (tagEnd < 0) return { code, changed: false, dynamic: false };
@@ -695,26 +603,9 @@ export function setClassName(code: string, elementStart: number, cls: string): S
   };
 }
 
-/**
- * Route a style edit to the right target (F5). TWO conditions gate the class
- * route, and the second one is the whole point:
- *
- *  1. the element has a literal `className` the class can be merged into, AND
- *  2. the PROJECT was observed to interpret utility classes
- *     (`support.supported` — see `utility-class-support.ts` for the probe and
- *     why it is strict).
- *
- * Without (2) a `bg-[#059669]` written into a plain-CSS project is inert: it
- * paints nothing in the editor after a remount and nothing in the game's own
- * build, because no transformer exists on either side to compile it. So no
- * evidence ⇒ the inline `style={{…}}` route, which paints in EVERY project,
- * leaving the element's literal className untouched.
- *
- * When neither target is honest — the element's style attribute is a dynamic
- * expression and there is no compiled class route to fall back to — this
- * REFUSES with a named reason (`changed: false`, `dynamic: true`, `error`)
- * rather than writing bytes that never paint.
- */
+/** Route to utility classes only for a literal className and proved project
+ * support. Otherwise write inline CSS. Refuse a dynamic style expression when
+ * there is no supported class route. */
 export function writeStyleAuto(
   code: string,
   elementStart: number,
@@ -754,7 +645,7 @@ export function writeStyleAuto(
   return { ...inline, route: 'inline' };
 }
 
-// --- Cap 2: CSS-file editing (visual-edit writer.ts surgicalCssEdit :1109) ---
+// CSS-file editing.
 
 /** camelCase CSS prop -> kebab-case, for matching a declaration in a CSS rule body. */
 export function cssCamelToKebab(s: string): string {
@@ -802,9 +693,8 @@ function findRuleBody(
 
 /**
  * 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 —
+ * source in place and preserving other declarations and formatting. 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(
@@ -846,14 +736,8 @@ export function surgicalCssEdit(
   return cssSource.slice(0, bodyEnd) + insertion + cssSource.slice(bodyEnd);
 }
 
-/**
- * The breakpoint write (design ledger: breakpoints): surgically edit — or
- * create — `selector`'s rule INSIDE a top-level `@media <media>` block,
- * creating the block itself when the stylesheet has none. The source keeps
- * real `@media` truth; the dev server's serve-time rewrite is what turns it
- * into a per-frame container query for preview. Conditions compare
- * whitespace-normalized, so `(max-width:767px)` finds `(max-width: 767px)`.
- */
+/** Edit or create a selector inside a top-level media block. Conditions
+ * compare after whitespace normalization; source remains ordinary CSS. */
 export function surgicalCssEditInMedia(
   cssSource: string,
   media: string,
@@ -911,21 +795,19 @@ export interface CssRuleTarget {
 
 /**
  * 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
+ * property (cascade — last declaration wins). Returns the rule, 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 {
+): CssRuleTarget | 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] ?? '' };
+  return target;
 }
 
 /**
@@ -1057,8 +939,7 @@ export function removeClassNameToken(
   return { code: code.slice(0, attrStart) + code.slice(attrEnd), changed: true, dynamic: false };
 }
 
-// --- Cap 3: text-content editing (visual-edit writer.ts getEditableText :817 /
-//     editTextContent :861) ---
+// Text-content editing.
 
 /** 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. */
@@ -1083,19 +964,6 @@ function findTextContentRange(
   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 {
@@ -1107,9 +975,8 @@ function escapeJsxText(text: string): string {
 }
 
 /**
- * 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.
+ * Replace only an element's trimmed text, preserving surrounding whitespace.
+ * Refuse bodies containing expressions or child elements (`dynamic: true`).
  */
 export function editTextContent(
   code: string,
@@ -1129,8 +996,7 @@ export function editTextContent(
   return { code: next, changed: next !== code, dynamic: false };
 }
 
-// --- Cap 4: JSX prop / attribute editing (visual-edit writer.ts analyzeJsxAttributes
-//     :913 / writePropChange :1018 / fetchPropAnalysis :1069) ---
+// JSX prop and attribute editing.
 
 export interface JsxAttrInfo {
   name: string;
@@ -1181,14 +1047,6 @@ function readQuotedValue(code: string, openQuote: number, delim: string): [numbe
 const NUMBER_LITERAL_SOURCE = String.raw`[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?`;
 const NUMBER_LITERAL_RE = new RegExp(`^${NUMBER_LITERAL_SOURCE}$`);
 
-/**
- * A NUMBER-TUPLE literal (`[0, 1.5, 0]`, any arity incl. empty,
- * ints/floats/negatives, whitespace/newlines/trailing comma tolerated). This
- * is the 3D value shape R3F props use for
- * `position`/`rotation`/`scale`/`args`; a tuple containing anything but a
- * plain signed number literal (`[x, 1, 0]`, `[f(), 0]`) is DYNAMIC and stays
- * behind the literal-vs-dynamic guard.
- */
 /**
  * A NUMBER-POINT literal (`{ x: 1.2, y: 0.8 }`): an object whose properties are all plain
  * identifiers with number values — the `PointData` a 2D scene's `scale` or `pivot` takes, and the
@@ -1207,6 +1065,14 @@ export function isNumberPointLiteral(raw: string): boolean {
   });
 }
 
+/**
+ * A NUMBER-TUPLE literal (`[0, 1.5, 0]`, any arity incl. empty,
+ * ints/floats/negatives, whitespace/newlines/trailing comma tolerated). This
+ * is the 3D value shape R3F props use for
+ * `position`/`rotation`/`scale`/`args`; a tuple containing anything but a
+ * plain signed number literal (`[x, 1, 0]`, `[f(), 0]`) is DYNAMIC and stays
+ * behind the literal-vs-dynamic guard.
+ */
 export function isNumberTupleLiteral(raw: string): boolean {
   const trimmed = raw.trim();
   if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return false;
@@ -1221,8 +1087,8 @@ export function isNumberTupleLiteral(raw: string): boolean {
 const LITERAL_EXPR_RE = new RegExp(`^(?:${NUMBER_LITERAL_SOURCE}|true|false|'[^']*'|"[^"]*")$`);
 
 /**
- * Parse the attributes of a JSX opening tag `<Tag …>` (visual-edit `analyzeJsxAttributes`
- * :913). Handles string values, `{expression}` values (literal detection), boolean
+ * Parse the attributes of a JSX opening tag `<Tag …>`: string values,
+ * `{expression}` values (literal detection), boolean
  * shorthand, and `{...spread}` (skipped). Pure string scan — no parser.
  */
 export function analyzeJsxAttributes(
@@ -1328,55 +1194,23 @@ function makeAttr(
   };
 }
 
-/** Props never surfaced as editable component props (visual-edit `fetchPropAnalysis` skip
- *  set + on* handlers — event handlers are always dynamic). */
+/** Internal props and event handlers excluded from component-prop editing. */
 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/tuple/quoted expression, or a plain string attribute). Returns `null` when the
- *  new value cannot take the original's shape (a non-tuple replacing a tuple) — the caller
- *  refuses rather than clobbering a structured literal with a quoted string.
- *
- *  `allowShapeUpgrade` (R2 — OPT-IN, default off so react-dom and every existing path are
- *  byte-identical): permits exactly ONE shape change — a plain number literal replaced by
- *  a number-TUPLE literal for the same prop (the R3F `scale={1.5}` scalar shorthand
- *  upgraded to `scale={[x, y, z]}` by a non-uniform gizmo drag). Dynamic values stay
- *  refused upstream (the `isLiteral` guard in {@link writePropChange} runs before this
- *  function is ever reached), and no other shape pair is upgraded. */
+/** Match a replacement to the original literal shape. An explicit
+ * allowShapeUpgrade permits a scalar number to become a numeric tuple or point;
+ * unsupported shapes return null. Dynamic values are refused by the caller. */
 function formatPropReplacement(
   attr: JsxAttrInfo,
   newValue: string,
-  allowShapeUpgrade = false,
+  allowShapeUpgrade: boolean,
 ): string | null {
   if (!attr.isExpression) return newValue; // string attribute — content between the quotes
   const raw = attr.rawValue;
   if (NUMBER_LITERAL_RE.test(raw)) {
     if (isNumberTupleLiteral(newValue) || isNumberPointLiteral(newValue)) {
-      // R2: a tuple replacing a plain number is a SHAPE CHANGE — allowed only
-      // under the explicit opt-in; otherwise refused outright (never the
-      // quoted-string fallback below, which would clobber `scale={1.5}` with
-      // a junk string literal).
+      // Scalar-to-tuple changes require explicit permission.
       return allowShapeUpgrade ? newValue.trim() : null;
     }
     const num = Number(newValue);
@@ -1385,8 +1219,7 @@ function formatPropReplacement(
   if (raw === 'true' || raw === 'false') {
     return newValue === 'true' || newValue === 'false' ? newValue : `'${newValue}'`;
   }
-  // W2 — a number-tuple literal is replaced ONLY by another number-tuple
-  // literal, verbatim (the caller controls spacing inside the brackets).
+  // Replace a number tuple only with another number tuple, preserving its spacing.
   if (isNumberTupleLiteral(raw)) {
     return isNumberTupleLiteral(newValue) ? newValue.trim() : null;
   }
@@ -1418,28 +1251,8 @@ function formatNewAttr(propName: string, newValue: string): string {
   return `${propName}="${newValue.replace(/"/g, '&quot;')}"`;
 }
 
-/**
- * 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 `<`.
- *
- * `opts.addIfMissing` (W2 — OPT-IN, default off so react-dom prop-write behavior is
- * unchanged): when the prop is absent from the opening tag, APPEND it (` prop={value}`
- * / ` prop="value"`) before the tag end instead of no-op'ing — the R3F gizmo path needs
- * this for a mesh whose source never authored a `position`/`rotation`/`scale` tuple
- * yet.
- *
- * `opts.allowShapeUpgrade` (R2 — OPT-IN, default off): permit a number-tuple literal to
- * replace a plain NUMBER literal for the same prop (scalar→tuple upgrade; see {@link
- * formatPropReplacement}). The R3F adapter passes it only for `scale` writes coming
- * from a non-uniform gizmo drag.
- */
-/**
- * Where to put a new attribute on a tag whose attributes each occupy their own
- * line, and with what indentation — or null when the tag is single-line and the
- * inline insert is right. Keyed off the LAST attribute actually starting a
- * line, so a tag mixing both styles follows its own majority tail.
- */
+/** Find the insertion position and indentation for a new multiline JSX
+ * attribute. Return null for a tag that uses inline attributes. */
 function ownLineAttributeInsert(
   code: string,
   elementStart: number,
@@ -1558,9 +1371,7 @@ export function removePropAttribute(
   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) ---
+// Source structural operations.
 
 export interface StructEditResult {
   code: string;
@@ -1586,8 +1397,7 @@ function lineBlockRange(
   return { lineStart, lineEnd };
 }
 
-/** The `<` of a parent's closing tag, given the parent's opening `<` (visual-edit's
- *  backwards scan from the element end). */
+/** Find a parent's closing tag by scanning backward from its element end. */
 function closingTagStartOf(code: string, parentStart: number): number | null {
   const parentEnd = findElementEnd(code, parentStart);
   if (parentEnd < 0) return null;
@@ -1630,32 +1440,8 @@ function offsetElementPosition(
   ).code;
 }
 
-/**
- * Shift every TOP-LEVEL element in a paste snippet by one offset — the block
- * moves as a unit, so relative arrangement inside the copy survives. A paste
- * that landed byte-identically ON its source read as "nothing was pasted"
- * to a human tester until they happened to drag the top one off.
- */
-export function offsetSnippetPositions(
-  snippet: string,
-  offset: readonly [number, number, number],
-): string {
-  let out = snippet;
-  let searchFrom = 0;
-  while (searchFrom < out.length) {
-    const start = out.indexOf('<', searchFrom);
-    if (start < 0) break;
-    if (findElementEnd(out, start) < 0) break;
-    out = offsetElementPosition(out, start, offset);
-    const end = findElementEnd(out, start);
-    if (end <= start) break;
-    searchFrom = end + 1;
-  }
-  return out;
-}
-
-/** Duplicate the element's line block, inserting the copy immediately after it (visual-edit
- *  `duplicateElement` :559). `rewrite` edits the copy only — see {@link DuplicateRewrite}. */
+/** Duplicate the element's line block immediately after it.
+ * `rewrite` edits only the copy — see {@link DuplicateRewrite}. */
 export function duplicateElement(
   code: string,
   elementStart: number,
@@ -1677,7 +1463,7 @@ export function duplicateElement(
 }
 
 /** Wrap the element in a new `<wrapperTag>…</wrapperTag>` container, re-indenting the
- *  wrapped block one level (visual-edit `wrapElement` :634). */
+ *  wrapped block one level. */
 export function wrapElement(
   code: string,
   elementStart: number,
@@ -1695,14 +1481,13 @@ export function wrapElement(
   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.
+/** Unwrap the element, replacing it with its children dedented one level.
+ *  A self-closing element simply deletes.
  *
  *  For the LINE-BLOCK shape — the opening tag ends its line and the closing tag sits alone
  *  on its own line, exactly what {@link wrapElement} writes — the newline after the opening
  *  tag and the closing tag's leading indent are consumed too, making unwrap the exact BYTE
- *  INVERSE of wrap (previously those survived as a stray blank line plus loose indentation
- *  merged into the following line). Inline children keep the original splice behavior. */
+ *  INVERSE of wrap. Inline children are spliced without line-boundary adjustment. */
 export function unwrapElement(code: string, elementStart: number): StructEditResult {
   if (code[elementStart] !== '<') return { code, changed: false };
   const end = findElementEnd(code, elementStart);
@@ -1735,16 +1520,9 @@ export function unwrapElement(code: string, elementStart: number): StructEditRes
   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).
- *
- *  `snippet` (R3 — optional; `tag` is ignored when it is provided): a MULTI-LINE JSX
- *  snippet inserted verbatim instead of the bare `<tag />`, each line re-indented one
- *  level under the parent (the R3F preset-create path needs a `<mesh>` with
- *  geometry+material children, not an empty tag). The snippet is authored flush-left with
- *  its own 2-space internal nesting; blank lines stay blank (no trailing whitespace).
- *  Must start with `<` — anything else is refused (`changed: false`), the same
- *  honest-refusal convention every other writer op uses. */
+/** Insert a child before the closing tag, matching child indentation.
+ * A supplied JSX snippet replaces the bare tag and is reindented by line;
+ * blank lines remain blank. Refuse snippets that do not start with <. */
 export function insertChildElement(
   code: string,
   parentStart: number,
@@ -1835,8 +1613,8 @@ export function insertSiblingElement(
 }
 
 /** 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. */
+ *  offset), or at the end of `parentStart` when `beforeStart` is null.
+ *  All offsets refer to the same source snapshot. */
 export function reorderChild(
   code: string,
   elementStart: number,
@@ -1869,20 +1647,8 @@ export function reorderChild(
   return { code: without.slice(0, adj) + block + without.slice(adj), changed: true };
 }
 
-/**
- * Turn `<Tag … />` into the paired `<Tag …>` / `</Tag>` shape, so the element has an
- * authored children slot to receive one.
- *
- * Why this exists (R3F reparent hardening, R3): in idiomatic R3F source almost every
- * hierarchy row IS a self-closing component callsite (`<JumpPad name="West" … />`), and
- * {@link reparentElement}'s `closingTagStartOf` scan finds the element's OWN `<` for such
- * a tag — so "drop into this row" silently became "insert a PRECEDING SIBLING". Opening
- * the slot is the honest edit an author would make by hand; it writes no value and
- * invents no data, it only gives the tag a body. The caller
- * (`reparent-guard.ts`) has already proven the destination renders its children.
- *
- * Refuses (`changed: false`) anything that is not a well-formed self-closing tag.
- */
+/** Open a well-formed self-closing tag into a paired tag with a children
+ * slot. The caller must establish that the destination renders children. */
 export function openChildrenSlot(code: string, elementStart: number): StructEditResult {
   if (code[elementStart] !== '<') return { code, changed: false };
   const tagEnd = findTagEnd(code, elementStart);
@@ -1904,7 +1670,7 @@ export function openChildrenSlot(code: string, elementStart: number): StructEdit
 }
 
 /** 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).
+ *  child level. The caller enforces same-file moves.
  *
  *  The R3F hierarchy calls this through `planReparent` (`reparent-guard.ts`), which owns
  *  the scope/transform/legality gates; this function stays the raw textual move. */
@@ -1943,7 +1709,7 @@ export function reparentElement(
   };
 }
 
-/** Delete the element starting at `elementStart` from source (C8). */
+/** Delete the element beginning at elementStart. */
 export function deleteElement(
   code: string,
   elementStart: number,
@@ -1958,27 +1724,9 @@ export function deleteElement(
   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).
- */
+/** Delete pre-resolved elements from one source snapshot, highest offset first.
+ * Earlier offsets remain valid as later elements disappear; descendants are
+ * removed before ancestors without reassigning occurrence-based OIDs. */
 export function deleteElements(
   code: string,
   elementStarts: readonly number[],