@volter/editor-react 0.5.66 → 0.5.68

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-react",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
-  "version": "0.5.66",
+  "version": "0.5.68",
   "publishConfig": {
     "access": "public"
   },
@@ -38,8 +38,8 @@
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.66",
-    "@volter/editor-project": "0.5.66",
+    "@volter/editor-sdk": "0.5.68",
+    "@volter/editor-project": "0.5.68",
     "typescript": "5.9.3"
   },
   "peerDependencies": {

package/serving/ui-oid-plugin.ts

@@ -97,6 +97,7 @@ import {
   transformSource,
 } from '../src/source/oid-transform';
 import { planDeleteStory, planRenameStory, planSaveStory } from '../src/source/plan-csf-story';
+import { writePropMember } from '../src/source/prop-member-writer';
 import { planComponentExtraction } from '../src/source/plan-extract-component';
 import { planComponentFork } from '../src/source/plan-fork-component';
 import { planCreateClassRule } from '../src/source/plan-named-style';
@@ -1004,6 +1005,13 @@ function handleProp(
   if (!entry) return { body: { changed: false, error: 'unknown oid' } };
   const src = readSettledSource(entry.file);
   const off = lineColToOffset(src, entry.line, entry.col);
+  // A dotted prop is one member of an object-literal prop (`params.threshold`): the index names
+  // members that way (`authoredProps`), and the member writer rewrites that literal alone.
+  if (prop.includes('.')) {
+    const member = writePropMember(src, off, prop.split('.'), value, { addIfMissing: body['addIfMissing'] === true });
+    if (member.changed) writeEditableSource(entry.file, member.code);
+    return { body: { changed: member.changed, dynamic: member.dynamic, file: entry.file } };
+  }
   // `value: null` is the REMOVAL sentinel, the same shape `/__ui-source/write`
   // uses for `removeStyle` (D-A3). Removing a prop attribute is how the
   // inspector reverts a prop to the component's declared default.
@@ -1530,7 +1538,7 @@ export function uiOidPlugin(
   // Captured by `configureServer` below, read by `transform` — the dev
   // server's own `ModuleGraph` is what lets `declaredSurfaceForProjectFileViaGraph`
   // reach a root entry's surface through a NON-entry file's importer chain
-  // (a child component with no direct fiber/world3d-react import of its
+  // (a child component with no direct fiber import of its
   // own). `undefined` in a build/SSR context without `configureServer`
   // (e.g. a one-off transform in a test) degrades to the direct-entry-only
   // answer, same as before this existed.

package/src/source/oid-transform.ts

@@ -11,6 +11,7 @@
  * an unrelated line keeps existing ids stable. The `data-oid` lives ONLY in the
  * transformed output, never on disk (the writer edits the original source instead).
  */
+import { isMemberLiteral, memberKey } from './prop-member-writer';
 import ts from 'typescript';
 import {
   environmentBindingsByElement,
@@ -44,24 +45,28 @@ export type {
 } from './r3f-particle-binding';
 export type { PhysicsChannel, R3fPhysicsBinding } from './r3f-physics-binding';
 
+/** A number as the writer reads one: `3`, `-3`, `+0.5` (the writer's `NUMBER_LITERAL_SOURCE`). */
+function signedNumericLiteral(expression: ts.Expression): boolean {
+  return (
+    ts.isNumericLiteral(expression) ||
+    (ts.isPrefixUnaryExpression(expression) &&
+      (expression.operator === ts.SyntaxKind.MinusToken || expression.operator === ts.SyntaxKind.PlusToken) &&
+      ts.isNumericLiteral(expression.operand))
+  );
+}
+
 function literalJsxExpression(expression: ts.Expression | undefined): boolean {
   if (!expression) return false;
   if (
     ts.isStringLiteral(expression) ||
-    ts.isNumericLiteral(expression) ||
+    signedNumericLiteral(expression) ||
     expression.kind === ts.SyntaxKind.TrueKeyword ||
     expression.kind === ts.SyntaxKind.FalseKeyword
   ) {
     return true;
   }
   if (!ts.isArrayLiteralExpression(expression)) return false;
-  return expression.elements.every(
-    (element) =>
-      ts.isNumericLiteral(element) ||
-      (ts.isPrefixUnaryExpression(element) &&
-        element.operator === ts.SyntaxKind.MinusToken &&
-        ts.isNumericLiteral(element.operand)),
-  );
+  return expression.elements.every(signedNumericLiteral);
 }
 
 function authoredPropsOf(
@@ -83,10 +88,49 @@ function authoredPropsOf(
         valueText: initializer.expression?.getText(sourceFile) ?? '',
         literal: literalJsxExpression(initializer.expression),
       },
+      ...(initializer.expression ? objectMembersOf(name, initializer.expression, sourceFile) : []),
     ];
   });
 }
 
+/**
+ * The members of an object-literal prop, each as its own authored prop under a dotted name
+ * (`params.threshold`, `params.bands.0.gain` through an array inside the object), with its own
+ * `literal`: `params={{ bank: BANK, program: 48 }}` is computed as a whole, and its `program` is
+ * still a literal a gesture may rewrite (`prop-member-writer.ts`). A top-level array stays one
+ * prop (a position tuple is written whole).
+ */
+function objectMembersOf(
+  prefix: string,
+  expression: ts.Expression,
+  sourceFile: ts.SourceFile,
+): NonNullable<OidEntry['authoredProps']> {
+  let node = expression;
+  while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) node = node.expression;
+  const entries: NonNullable<OidEntry['authoredProps']> = [];
+  const visit = (name: string, value: ts.Expression): void => {
+    let inner = value;
+    while (ts.isParenthesizedExpression(inner) || ts.isAsExpression(inner) || ts.isSatisfiesExpression(inner)) inner = inner.expression;
+    if (ts.isObjectLiteralExpression(inner) || ts.isArrayLiteralExpression(inner)) {
+      walk(name, inner);
+      return;
+    }
+    entries.push({ name, valueText: value.getText(sourceFile), literal: isMemberLiteral(value) });
+  };
+  const walk = (name: string, container: ts.ObjectLiteralExpression | ts.ArrayLiteralExpression): void => {
+    if (ts.isArrayLiteralExpression(container)) {
+      container.elements.forEach((element, index) => visit(`${name}.${index}`, element));
+      return;
+    }
+    for (const property of container.properties) {
+      const key = memberKey(property);
+      if (key !== null && ts.isPropertyAssignment(property)) visit(`${name}.${key}`, property.initializer);
+    }
+  };
+  if (ts.isObjectLiteralExpression(node)) walk(prefix, node);
+  return entries;
+}
+
 /** Persistent oid store: signature -> oid (kept stable across re-transforms). */
 export class OidStore {
   private bySig = new Map<string, string>();
@@ -991,8 +1035,7 @@ export function sourceDialectEvidence(code: string): SourceDialectEvidence {
   const scanned = stripCommentsForScan(code);
   return {
     reconcilerImport:
-      scanned.includes('@react-three/fiber') ||
-      scanned.includes('@vgai/game-runtime/world3d-react'),
+      scanned.includes('@react-three/fiber'),
     r3fOnlyTags: distinctTags(scanned, R3F_ONLY_INTRINSIC_RE),
     domOnlyTags: distinctTags(scanned, DOM_ONLY_INTRINSIC_RE),
   };
@@ -1013,8 +1056,8 @@ export function sourceProvesR3f(evidence: SourceDialectEvidence): boolean {
  *    reaches it. `'three'` stamps `userData-oid`; `'canvas'`/`'dom'` stamp
  *    `data-oid`. It is resolved from OUTSIDE the file, exactly where the fact
  *    lives, which is what makes it right for a world whose entry
- *    default-exports a component and imports NEITHER `@react-three/fiber` nor
- *    `@vgai/game-runtime/world3d-react` (legal: R3F's global JSX-intrinsics augmentation,
+ *    default-exports a component and does not import `@react-three/fiber`
+ *    (legal: R3F's global JSX-intrinsics augmentation,
  *    or an entry composed entirely of already-typed child components, needs no
  *    import in THIS file). Every call site threads it from a context that
  *    resolved it per file: `binding-resolver.ts`'s per-surface resolvers, the
@@ -1326,6 +1369,21 @@ function reactFragmentNames(sf: ts.SourceFile): Set<string> {
  * into game DOM. That preserves per-instance source identity without inserting
  * a wrapper into the native tree. Returns the transformed code + index entries.
  */
+/** Whether any JSX (an element, a self-closing element or a fragment) appears under `node`. */
+function containsJsx(node: ts.Node): boolean {
+  let found = false;
+  const visit = (child: ts.Node): void => {
+    if (found) return;
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child)) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(child, visit);
+  };
+  ts.forEachChild(node, visit);
+  return found;
+}
+
 export function transformSource(
   code: string,
   file: string,
@@ -1420,8 +1478,14 @@ export function transformSource(
   const pushComponent = (
     name: string | undefined,
     parameters: ts.NodeArray<ts.ParameterDeclaration> | undefined,
+    body: ts.Node,
   ): boolean => {
     if (!name || !/^[A-Z]/.test(name) || !parameters) return false;
+    // A capitalised function that renders no JSX is not a component, whatever its name: a table
+    // helper like `const PATCH = (key) => ({ key, … })` had its parameter rewritten into props
+    // destructuring and received an object of its string's characters. Nothing in it is stamped,
+    // and it consumes no transport props, so it is left as written.
+    if (!containsJsx(body)) return false;
     // Component membership participates in the stable OID signature on every
     // JSX dialect. Three/Canvas callsites inject the transport props, while
     // every project component consumes them: a component declared on a DOM
@@ -1461,14 +1525,14 @@ export function transformSource(
   const visit = (node: ts.Node): void => {
     let pushed = false;
     if (ts.isFunctionDeclaration(node) && node.name)
-      pushed = pushComponent(node.name.text, node.parameters);
+      pushed = pushComponent(node.name.text, node.parameters, node);
     else if (
       ts.isVariableDeclaration(node) &&
       ts.isIdentifier(node.name) &&
       node.initializer &&
       (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))
     ) {
-      pushed = pushComponent(node.name.text, node.initializer.parameters);
+      pushed = pushComponent(node.name.text, node.initializer.parameters, node.initializer);
     }
 
     if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {

package/src/source/plan-source-edit.ts

@@ -349,5 +349,8 @@ export function planSourceEdit(
           request.ensureImport.kind,
         ).code
       : result.code;
-  return planned(entry.file, src, code, { changed: result.changed });
+  return planned(entry.file, src, code, {
+    changed: result.changed,
+    ...(result.error ? { error: result.error } : {}),
+  });
 }

package/src/source/prop-member-writer.ts

@@ -0,0 +1,126 @@
+/**
+ * ONE MEMBER OF AN OBJECT-LITERAL PROP, written at the call site: `params.threshold` in
+ * `<Device params={{ threshold: -20, ratio: 1.5 }} />`, `params.bands.0.gain` through an array.
+ * The same rule every other prop write keeps: only a literal is rewritten (a member bound to an
+ * expression answers `dynamic`), and nothing else in the file moves. A missing member is added
+ * to its object when asked (`addIfMissing`); `null` takes the member out.
+ *
+ * `writer.ts` scans strings so the page can run it; this one parses the expression with
+ * TypeScript and runs only in the serving process.
+ */
+
+import ts from 'typescript';
+import { analyzeJsxAttributes, findTagEnd } from './writer';
+
+export interface MemberEditResult {
+  readonly code: string;
+  readonly changed: boolean;
+  readonly dynamic: boolean;
+}
+
+const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** A literal written into an object: numbers and booleans bare, anything else a quoted string. */
+function formatMember(value: string): string {
+  if (NUMBER.test(value.trim()) || value === 'true' || value === 'false') return value.trim();
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/** Whether an expression is a literal a gesture may replace: string, number (signed), boolean. */
+export function isMemberLiteral(node: ts.Expression): boolean {
+  return (
+    ts.isStringLiteral(node) ||
+    ts.isNoSubstitutionTemplateLiteral(node) ||
+    ts.isNumericLiteral(node) ||
+    node.kind === ts.SyntaxKind.TrueKeyword ||
+    node.kind === ts.SyntaxKind.FalseKeyword ||
+    (ts.isPrefixUnaryExpression(node) &&
+      (node.operator === ts.SyntaxKind.MinusToken || node.operator === ts.SyntaxKind.PlusToken) &&
+      ts.isNumericLiteral(node.operand))
+  );
+}
+
+/** A property's key as written (`threshold`, `'high-pass'`), or `null` when it is computed. */
+export function memberKey(property: ts.ObjectLiteralElementLike): string | null {
+  if (!ts.isPropertyAssignment(property)) return null;
+  const name = property.name;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  return null;
+}
+
+function unwrap(node: ts.Expression): ts.Expression {
+  let current = node;
+  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+export function writePropMember(
+  code: string,
+  elementStart: number,
+  path: readonly string[],
+  newValue: string | null,
+  opts?: { addIfMissing?: boolean },
+): MemberEditResult {
+  const unchanged = { code, changed: false, dynamic: false };
+  const [propName, ...members] = path;
+  if (!propName || members.length === 0 || code[elementStart] !== '<') return unchanged;
+  const tagEnd = findTagEnd(code, elementStart);
+  if (tagEnd < 0) return unchanged;
+  const attr = analyzeJsxAttributes(code, elementStart, tagEnd).find((candidate) => candidate.name === propName);
+  if (!attr || !attr.isExpression) return { code, changed: false, dynamic: attr !== undefined };
+  // Parse the expression alone, in parentheses (a bare `{ … }` is a block): an offset in it,
+  // less one, is an offset from `attr.valueStart`.
+  const text = `(${code.slice(attr.valueStart, attr.valueEnd)})`;
+  const file = ts.createSourceFile('member.tsx', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const statement = file.statements[0];
+  if (!statement || !ts.isExpressionStatement(statement)) return { code, changed: false, dynamic: true };
+  let container = unwrap(statement.expression);
+  const splice = (start: number, end: number, insert: string): MemberEditResult => {
+    const next = code.slice(0, attr.valueStart + start - 1) + insert + code.slice(attr.valueStart + end - 1);
+    return { code: next, changed: next !== code, dynamic: false };
+  };
+  for (let depth = 0; depth < members.length; depth++) {
+    const key = members[depth]!;
+    const last = depth === members.length - 1;
+    if (ts.isArrayLiteralExpression(container)) {
+      const element = /^\d+$/.test(key) ? container.elements[Number(key)] : undefined;
+      if (!element) return { code, changed: false, dynamic: false };
+      if (!last) {
+        container = unwrap(element);
+        continue;
+      }
+      if (newValue === null || !isMemberLiteral(element)) return { code, changed: false, dynamic: !isMemberLiteral(element) };
+      return splice(element.getStart(file), element.end, formatMember(newValue));
+    }
+    if (!ts.isObjectLiteralExpression(container)) return { code, changed: false, dynamic: true };
+    const properties = container.properties;
+    const property = properties.find((candidate) => memberKey(candidate) === key);
+    // A spread or computed key could supply this member: the source does not say which value wins.
+    const opaque = properties.some((candidate) => ts.isSpreadAssignment(candidate) || (ts.isPropertyAssignment(candidate) && memberKey(candidate) === null));
+    if (!property || !ts.isPropertyAssignment(property)) {
+      if (!last || newValue === null || !opts?.addIfMissing) return unchanged;
+      if (opaque) return { code, changed: false, dynamic: true };
+      const entry = `${/^[A-Za-z_$][\w$]*$/.test(key) ? key : `'${key}'`}: ${formatMember(newValue)}`;
+      const lastProperty = properties[properties.length - 1];
+      if (!lastProperty) return splice(container.getStart(file) + 1, container.end - 1, ` ${entry} `);
+      return splice(lastProperty.end, lastProperty.end, `, ${entry}`);
+    }
+    const value = unwrap(property.initializer);
+    if (!last) {
+      container = value;
+      continue;
+    }
+    if (!isMemberLiteral(property.initializer)) return { code, changed: false, dynamic: true };
+    if (newValue !== null) return splice(property.initializer.getStart(file), property.initializer.end, formatMember(newValue));
+    // Take the member out with the comma that separates it from its neighbour.
+    const index = properties.indexOf(property);
+    const next = properties[index + 1];
+    const previous = properties[index - 1];
+    if (next) return splice(property.getStart(file), next.getStart(file), '');
+    if (previous) return splice(previous.end, properties.hasTrailingComma ? property.end + 1 : property.end, '');
+    return splice(container.getStart(file) + 1, container.end - 1, '');
+  }
+  return unchanged;
+}

package/src/source/r3f-project-contracts.ts

@@ -135,7 +135,7 @@ export function visibleR3fContracts(code: string, file: string): Map<string, R3f
  * `export default World` or `export default function World() {…}`.
  *
  * A three root's entry module default-exports its component (D26,
- * `r3fRootFactory`) — the same contract dom roots use. That component IS the
+ * the editor's `roots/r3f-root.tsx`) — the same contract dom roots use. That component IS the
  * adapter root, so the single-spatial-root rule must not fire on it: a world
  * legitimately returns a fragment of lights, scenery and players.
  */

package/src/source/writer.ts

@@ -1189,6 +1189,24 @@ const NUMBER_LITERAL_RE = new RegExp(`^${NUMBER_LITERAL_SOURCE}$`);
  * 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
+ * one object shape this writer treats as a literal (a Pixi tag's non-uniform `scale`).
+ */
+export function isNumberPointLiteral(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return false;
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner === '') return false;
+  const parts = inner.split(',').map((p) => p.trim());
+  if (parts.length > 1 && parts[parts.length - 1] === '') parts.pop();
+  return parts.every((part) => {
+    const match = /^([A-Za-z_$][\w$]*)\s*:\s*(.+)$/.exec(part);
+    return match !== null && NUMBER_LITERAL_RE.test(match[2]!.trim());
+  });
+}
+
 export function isNumberTupleLiteral(raw: string): boolean {
   const trimmed = raw.trim();
   if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return false;
@@ -1294,7 +1312,10 @@ function makeAttr(
 ): JsxAttrInfo {
   const rawValue = code.slice(parsed.valueStart, parsed.valueEnd).trim();
   const isLiteral =
-    !parsed.isExpression || LITERAL_EXPR_RE.test(rawValue) || isNumberTupleLiteral(rawValue);
+    !parsed.isExpression ||
+    LITERAL_EXPR_RE.test(rawValue) ||
+    isNumberTupleLiteral(rawValue) ||
+    isNumberPointLiteral(rawValue);
   return {
     name,
     valueStart: parsed.valueStart,
@@ -1351,7 +1372,7 @@ function formatPropReplacement(
   if (!attr.isExpression) return newValue; // string attribute — content between the quotes
   const raw = attr.rawValue;
   if (NUMBER_LITERAL_RE.test(raw)) {
-    if (isNumberTupleLiteral(newValue)) {
+    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
@@ -1369,6 +1390,12 @@ function formatPropReplacement(
   if (isNumberTupleLiteral(raw)) {
     return isNumberTupleLiteral(newValue) ? newValue.trim() : null;
   }
+  // A number-point literal is replaced by another point, or by a plain number (a scale made
+  // uniform again); anything else is a shape it cannot take.
+  if (isNumberPointLiteral(raw)) {
+    if (isNumberPointLiteral(newValue)) return newValue.trim();
+    return NUMBER_LITERAL_RE.test(newValue.trim()) ? newValue.trim() : null;
+  }
   if (/^"[^"]*"$/.test(raw)) return `"${newValue.replace(/"/g, '\\"')}"`;
   return `'${newValue.replace(/'/g, "\\'")}'`;
 }
@@ -1381,6 +1408,7 @@ function formatPropReplacement(
 function formatNewAttr(propName: string, newValue: string): string {
   if (
     isNumberTupleLiteral(newValue) ||
+    isNumberPointLiteral(newValue) ||
     NUMBER_LITERAL_RE.test(newValue) ||
     newValue === 'true' ||
     newValue === 'false'
@@ -1537,6 +1565,8 @@ export function removePropAttribute(
 export interface StructEditResult {
   code: string;
   changed: boolean;
+  /** Why an op that could not apply refused, when it can say. */
+  error?: string;
 }
 
 /** Expand a JSX element at `elementStart` to its full LINE block (leading whitespace on the
@@ -1721,13 +1751,11 @@ export function insertChildElement(
   tag = 'div',
   snippet?: string,
 ): StructEditResult {
-  const closingTagStart = closingTagStartOf(code, parentStart);
-  if (closingTagStart == null) return { code, changed: false };
+  const tagEnd = findTagEnd(code, parentStart);
+  if (tagEnd < 0) 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 childIndent = `${parentIndent}  `;
   let child: string;
   if (snippet !== undefined) {
@@ -1740,6 +1768,26 @@ export function insertChildElement(
   } else {
     child = `${childIndent}<${tag} />\n`;
   }
+  // A self-closing parent (`<Transport tempo={92} />`) has no children yet: it opens, takes the
+  // child, and closes on its own line. Walking back to a `<` from its end would find the parent's
+  // OWN tag and put the child beside it.
+  if (code[tagEnd - 1] === '/') {
+    const name = code.slice(parentStart + 1, tagEnd).match(/^([A-Za-z0-9_.$:-]+)/)?.[1];
+    if (!name) return { code, changed: false };
+    let open = tagEnd - 1;
+    while (open > parentStart && /\s/.test(code[open - 1] ?? '')) open--;
+    const opened = `${code.slice(0, open)}>\n${child}${parentIndent}</${name}>`;
+    return { code: opened + code.slice(tagEnd + 1), changed: true };
+  }
+  const closingTagStart = closingTagStartOf(code, parentStart);
+  if (closingTagStart == null) return { code, changed: false };
+  // The child goes on its own line before the closing tag: at that line's start when the closing
+  // tag begins its line, else (a one-line parent, `<Clip>…</Clip>`) broken onto a new line there.
+  let insertPos = closingTagStart;
+  while (insertPos > 0 && (code[insertPos - 1] === ' ' || code[insertPos - 1] === '\t')) insertPos--;
+  if (insertPos > 0 && code[insertPos - 1] !== '\n') {
+    return { code: `${code.slice(0, closingTagStart)}\n${child}${parentIndent}${code.slice(closingTagStart)}`, changed: true };
+  }
   return { code: code.slice(0, insertPos) + child + code.slice(insertPos), changed: true };
 }
 
@@ -1763,6 +1811,19 @@ export function insertSiblingElement(
 ): StructEditResult {
   const trimmed = snippet.trim();
   if (!trimmed.startsWith('<')) return { code, changed: false };
+  // A sibling is legal only beside a JSX CHILD: an element whose text is preceded by a tag's `>`
+  // (not an arrow's `=>`) or an expression child's `}`. The lone element a component returns has no JSX parent, and a
+  // second element beside it is a syntax error, never an insert.
+  let before = elementStart - 1;
+  while (before >= 0 && /\s/.test(code[before]!)) before--;
+  const arrowBody = code[before] === '>' && code[before - 1] === '=';
+  if (before < 0 || arrowBody || (code[before] !== '>' && code[before] !== '}')) {
+    return {
+      code,
+      changed: false,
+      error: 'this element is not a JSX child (a lone returned element), so it can have no sibling.',
+    };
+  }
   const r = lineBlockRange(code, elementStart);
   if (!r) return { code, changed: false };
   const indent = code.slice(r.lineStart, elementStart).match(/^(\s*)/)?.[1] ?? '';