@volter/editor-react 0.5.67 → 0.5.69

package/NOTICE

@@ -1,4 +1,4 @@
 Copyright 2026 Volter AI, Inc.
 
-The files in this package were imported from volter-ai/vgai-engine at commit
+The files in this package were imported from volter-ai/volter-engine at commit
 09c2749ce. LICENSE contains the AGPL-3.0-only license they retain.

package/contributions/component-contracts.service.ts

@@ -2,7 +2,7 @@
  * The component-contract analyzer, registered for the browser (a `workspace.service`
  * contribution): what the kit's Content index reads when it indexes a project from storage,
  * with no session server to ask (`@volter/editor-sdk/source-analysis`). The session's server
- * registers the same analyzer through this package's `vgai.serving` module.
+ * registers the same analyzer through this package's `volter.serving` module.
  */
 
 import { registerComponentContractAnalyzer } from '@volter/editor-sdk/source-analysis';

package/dist-node/serving.mjs

@@ -1114,6 +1114,16 @@ ${child}${parentIndent}${code.slice(closingTagStart)}`, changed: true };
 function insertSiblingElement(code, elementStart, snippet) {
   const trimmed = snippet.trim();
   if (!trimmed.startsWith("<")) return { code, changed: false };
+  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] ?? "";
@@ -2708,31 +2718,31 @@ function transformSource(code, file, store, opts) {
   const componentInstanceExpressions = (parameters) => {
     const first = parameters[0];
     if (!first) {
-      sourceEdits.push({ pos: parameters.pos, text: "{ __vgaiOid, __vgaiLabel } = {}" });
-      return { instanceExpression: "__vgaiOid", labelExpression: "__vgaiLabel" };
+      sourceEdits.push({ pos: parameters.pos, text: "{ __volterOid, __volterLabel } = {}" });
+      return { instanceExpression: "__volterOid", labelExpression: "__volterLabel" };
     }
     if (ts8.isObjectBindingPattern(first.name)) {
       sourceEdits.push({
         pos: first.name.getStart(sf) + 1,
-        text: "__vgaiOid, __vgaiLabel, "
+        text: "__volterOid, __volterLabel, "
       });
       if (!first.initializer) {
         sourceEdits.push({ pos: first.getEnd(), text: " = {}" });
       }
-      return { instanceExpression: "__vgaiOid", labelExpression: "__vgaiLabel" };
+      return { instanceExpression: "__volterOid", labelExpression: "__volterLabel" };
     }
     if (ts8.isIdentifier(first.name) && !first.dotDotDotToken) {
       sourceEdits.push({
         pos: first.name.getStart(sf),
         end: first.questionToken?.end ?? first.name.getEnd(),
-        text: `{ __vgaiOid, __vgaiLabel, ...${first.name.text} }`
+        text: `{ __volterOid, __volterLabel, ...${first.name.text} }`
       });
       if (!first.initializer) {
         sourceEdits.push({ pos: first.getEnd(), text: " = {}" });
       }
-      return { instanceExpression: "__vgaiOid", labelExpression: "__vgaiLabel" };
+      return { instanceExpression: "__volterOid", labelExpression: "__volterLabel" };
     }
-    return { instanceExpression: "__vgaiOid", labelExpression: "__vgaiLabel" };
+    return { instanceExpression: "__volterOid", labelExpression: "__volterLabel" };
   };
   const pushComponent = (name, parameters, body) => {
     if (!name || !/^[A-Z]/.test(name) || !parameters) return false;
@@ -2811,10 +2821,10 @@ function transformSource(code, file, store, opts) {
             (property2) => ts8.isJsxAttribute(property2) && property2.name.getText(sf) === "name"
           );
           const label = authoredName?.initializer && ts8.isStringLiteral(authoredName.initializer) ? authoredName.initializer.text : tag;
-          const labelAttribute = authoredName?.initializer && ts8.isJsxExpression(authoredName.initializer) ? `__vgaiLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}` : `__vgaiLabel=${JSON.stringify(label)}`;
+          const labelAttribute = authoredName?.initializer && ts8.isJsxExpression(authoredName.initializer) ? `__volterLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}` : `__volterLabel=${JSON.stringify(label)}`;
           sourceEdits.push({
             pos: node.attributes.end,
-            text: ` __vgaiOid="${oid}" ${labelAttribute}`
+            text: ` __volterOid="${oid}" ${labelAttribute}`
           });
         }
       } else {
@@ -3477,7 +3487,7 @@ function r3fAuthoringDiagnostics(code, file, opts) {
           message: `${rootComponent} animates its authored outer root through useFrame. Keep the outer root stable and animate an inner child so editor transforms do not fight runtime motion.`
         });
       }
-      if (/^[A-Z]/.test(tag) && contract?.root === "single" && // A package component vgai knows only through the built-in table is not
+      if (/^[A-Z]/.test(tag) && contract?.root === "single" && // A package component volter knows only through the built-in table is not
       // a hierarchy row of its own — `<RigidBody>` never receives the editor's
       // stamp, so its props are attributed to the node it wraps
       // (`collapsedWrappersOf`). Naming it would name nothing.
@@ -3515,8 +3525,8 @@ import { existsSync as existsSync2 } from "node:fs";
 import { join } from "node:path";
 
 // ../editor-project/src/manifest/filename.ts
-var MANIFEST_FILENAME = "vgai.project.json";
-var REMOVED_MANIFEST_FILENAME = "vgai.game.json";
+var MANIFEST_FILENAME = "volter.project.json";
+var REMOVED_MANIFEST_FILENAME = "volter.game.json";
 function removedManifestFilenameMessage(where) {
   return `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. \`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, docs/ARCHITECTURE-CORE.md \xA7Vocabulary) \u2014 nothing reads it any more, and it is deliberately NOT read as a fallback, because a second accepted name is the defect.
 Fix: rename it \u2014 \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. The contents are unchanged; only the filename moved.`;
@@ -3534,7 +3544,7 @@ function resolveManifestPath(dir) {
 }
 
 // ../editor-sdk/src/session/project-serving.ts
-var SOURCE_WRITE_ROUTES_PLUGIN = "vgai-ui-oid";
+var SOURCE_WRITE_ROUTES_PLUGIN = "volter-ui-oid";
 
 // ../editor-sdk/src/css-numeric-style.ts
 var UNITLESS_NUMBER_PROPS = /* @__PURE__ */ new Set([
@@ -3674,7 +3684,7 @@ function planDeleteStory(source, name) {
   if (outside.includes(`defaultStory: '${name}'`) || outside.includes(`defaultStory: "${name}"`)) {
     return {
       ok: false,
-      reason: `'${name}' is this file's declared defaultStory \u2014 point vgai.defaultStory at another story first`
+      reason: `'${name}' is this file's declared defaultStory \u2014 point volter.defaultStory at another story first`
     };
   }
   return { ok: true, nextSource: outside, summary: `story '${name}' deleted` };
@@ -4236,7 +4246,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  parameters: { vgai: { default: true } },
+  parameters: { volter: { default: true } },
 };
 `;
   const importSpecifier = relativeImportSpecifier(normalizePath(request.sourceFile), componentFile);
@@ -5006,7 +5016,10 @@ function planSourceEdit(request, sources, resolveOid, utilityClasses = UTILITY_C
     request.ensureImport.module,
     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 } : {}
+  });
 }
 
 // src/source/r3f-diagnostic-index.ts
@@ -5035,7 +5048,7 @@ function fileDiagnosticJoin(fileEntries, fileDiagnostics) {
 
 // serving/ui-oid-plugin.ts
 var NODE_MODULES_RE = /\/node_modules\//;
-var TOOLING_SRC_RE = /\/packages\/(engine\/src|create-vgai-project|vgai-cli|editor-sdk)\//;
+var TOOLING_SRC_RE = /\/packages\/(engine\/src|create-volter-project|volter-cli|editor-sdk)\//;
 var EDITOR_SRC_RE = /\/packages\/editor\/src\//;
 var EDITABLE_COMPONENTS_RE = /\/ui-editor\/editable-components\/.*\.tsx$/;
 var VENDOR_RE = /\/vendor\//;
@@ -5092,7 +5105,7 @@ function sourceResourcePath(file, projectRoot) {
   const path = relative(projectRoot, file).replace(/\\/g, "/");
   if (path && path !== ".." && !path.startsWith("../") && !isAbsolute(path)) return path;
   const identity = createHash("sha256").update(file).digest("hex").slice(0, 16);
-  return `.vgai/external-source/${identity}/${basename(file)}`;
+  return `.volter/external-source/${identity}/${basename(file)}`;
 }
 var utilityClassSupport = /* @__PURE__ */ new Map();
 function owningPackageDir(file, fallback) {
@@ -5117,7 +5130,7 @@ function utilityClassEvidence(dir) {
     const absolute = join2(dir, name);
     if (existsSync3(absolute)) read(absolute, name);
   }
-  const skip = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git", ".vgai", ".claude"]);
+  const skip = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git", ".volter", ".claude"]);
   let budget = 80;
   const walk = (current, prefix, depth) => {
     if (depth > 3 || budget <= 0) return;
@@ -5241,7 +5254,7 @@ function rejectPendingPropRequests(error) {
 }
 function declaredPropWorker() {
   if (propWorker) return propWorker;
-  const worker = new Worker(componentPropWorkerUrl(), { name: "vgai-component-props" });
+  const worker = new Worker(componentPropWorkerUrl(), { name: "volter-component-props" });
   worker.on(
     "message",
     (message) => {
@@ -5877,8 +5890,8 @@ function uiOidPlugin(services, include = defaultProjectScopeInclude) {
         try {
           const body = await readJson(req);
           const claimedParticipantId = body["participantId"];
-          const trustedParticipantId = req.headers["x-vgai-share-participant-id"];
-          const trustedRole = req.headers["x-vgai-share-role"];
+          const trustedParticipantId = req.headers["x-volter-share-participant-id"];
+          const trustedRole = req.headers["x-volter-share-role"];
           if (typeof trustedParticipantId === "string" && typeof claimedParticipantId === "string" && trustedParticipantId !== claimedParticipantId) {
             throw new Error(
               "The authenticated share participant does not match the source mutation author."
@@ -5943,10 +5956,10 @@ function uiOidPlugin(services, include = defaultProjectScopeInclude) {
           const index = currentOidIndex(store, activeProjectRoot(), server);
           res.setHeader("Server-Timing", `index;dur=${Date.now() - indexStarted}`);
           res.setHeader(
-            "X-Vgai-Oid-Index-Enriched",
+            "X-Volter-Oid-Index-Enriched",
             index === lastEnrichedIndex?.index ? "1" : "0"
           );
-          if (typeof req.headers["x-vgai-share-participant-id"] !== "string") {
+          if (typeof req.headers["x-volter-share-participant-id"] !== "string") {
             return json(res, index);
           }
           return json(

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-react",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
-  "version": "0.5.67",
+  "version": "0.5.69",
   "publishConfig": {
     "access": "public"
   },
@@ -31,15 +31,15 @@
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json"
   },
-  "vgai": {
+  "volter": {
     "contributions": [
       "./contributions/component-contracts.service.ts"
     ],
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.67",
-    "@volter/editor-project": "0.5.67",
+    "@volter/editor-sdk": "0.5.69",
+    "@volter/editor-project": "0.5.69",
     "typescript": "5.9.3"
   },
   "peerDependencies": {

package/serving/index.ts

@@ -1,5 +1,5 @@
 /**
- * `@volter/editor-react`'s server half (`package.json#vgai.serving`, the project-serving door in
+ * `@volter/editor-react`'s server half (`package.json#volter.serving`, the project-serving door in
  * `@volter/editor-sdk/session/project-serving`): the JSX identity stamp and the `/__ui-source/*`
  * authoring routes over a project's React and React Three Fiber source, and the source answers
  * the kit's region decision, validation and Content index ask of a JSX lane.

package/serving/ui-oid-plugin.ts

@@ -19,13 +19,13 @@
  * dev-server `fs.allow` pipeline `server/dev.ts` already builds for project scripts
  * (T3.3) — so `ReactRootAuthoringAdapter` needs those files instrumented too.
  * `defaultProjectScopeInclude` widens to PROJECT scope, not repo-global: any `.tsx`
- * file outside `node_modules`, EXCEPT the vgai tooling/engine source trees this repo
- * itself is built from (`packages/engine/src`, `packages/create-vgai-project`,
- * `packages/vgai-cli`, `packages/editor-sdk`, and `packages/editor/src` generally —
+ * file outside `node_modules`, EXCEPT the volter tooling/engine source trees this repo
+ * itself is built from (`packages/engine/src`, `packages/create-volter-project`,
+ * `packages/volter-cli`, `packages/editor-sdk`, and `packages/editor/src` generally —
  * carving OUT `ui-editor/editable-components` so the existing UI-edit-mode surface
  * keeps working unchanged). This does NOT depend on which project happens to be
  * open — `fs.allow` already bounds what Vite can even reach, and this predicate
- * additionally keeps the vgai app's OWN react source un-instrumented.
+ * additionally keeps the volter app's OWN react source un-instrumented.
  *
  * Vendored trees: a vendored GAME's source is STAMPED; every other `/vendor/`
  * tree is not. `data-oid` stamping is what makes a `.tsx` file addressable —
@@ -53,11 +53,11 @@
  * the write-back ban becomes IDENTITY-scoped, not just location-scoped: the
  * `/vendor/` regex above only protects the repo's OWN vendored trees, but
  * wave 2 lets an `ingest-react` world live in ANY external, user-owned
- * folder (`vgai edit <folder>`) — an ingested-as-is foreign game there would
+ * folder (`volter-game-editor edit <folder>`) — an ingested-as-is foreign game there would
  * otherwise be silently stamped/writable, reopening the never-modify-game-
  * source rule by location rather than by identity. `nearestManifestExcludesIngestReact`
  * walks up from a candidate `.tsx`'s own directory to the NEAREST
- * `vgai.project.json`; if that manifest declares an `{ ingest }` react world,
+ * `volter.project.json`; if that manifest declares an `{ ingest }` react world,
  * the whole manifest folder's subtree is excluded — exact, not coarse:
  * `ingest-react` is single-world by construction (`binding-resolver.ts`'s
  * `MULTI_WORLD_ALLOWED_IDENTITIES` exclusion), so "the manifest folder" IS
@@ -146,7 +146,7 @@ import {
 export { applyStyleWriteRequest, oidAttributeForSurface };
 
 const NODE_MODULES_RE = /\/node_modules\//;
-const TOOLING_SRC_RE = /\/packages\/(engine\/src|create-vgai-project|vgai-cli|editor-sdk)\//;
+const TOOLING_SRC_RE = /\/packages\/(engine\/src|create-volter-project|volter-cli|editor-sdk)\//;
 const EDITOR_SRC_RE = /\/packages\/editor\/src\//;
 const EDITABLE_COMPONENTS_RE = /\/ui-editor\/editable-components\/.*\.tsx$/;
 /** Track N, D-N4 item 2 — see the module doc comment's "Vendored-tree exclusion". */
@@ -170,13 +170,13 @@ const VENDOR_RE = /\/vendor\//;
  */
 const VENDORED_GAME_SRC_RE = /\/vendor\/games\/[^/]+\//;
 
-/** True if a parsed `vgai.project.json` body declares at least one
+/** True if a parsed `volter.project.json` body declares at least one
  *  React root with an `{ ingest }` adapter — the `{ ingest }` shape alone is
  *  the answer, because every ingest-react root is D-N8 no-authoring.
  *  Defensive against
  *  any shape (never trusts the manifest is even an object) — this is a
  *  best-effort identity probe for a WRITE-BACK BAN, not manifest validation
- *  (the real Zod schema/loader is `@vgai/project/manifest/load`, not reachable
+ *  (the real Zod schema/loader is `@volter/project/manifest/load`, not reachable
  *  from this vite-config-time, dependency-light file by design). */
 function manifestDeclaresIngestReactWorld(parsed: unknown): boolean {
   if (!parsed || typeof parsed !== 'object') return false;
@@ -236,7 +236,7 @@ function nearestManifestExcludesIngestReact(dir: string): boolean {
  * Cap 2 (React visual-edit parity): the scope guard for the `/__ui-source/css` endpoint.
  * A CSS file path (from a stylesheet's `data-vite-dev-id`) is editable iff it is a
  * first-party PROJECT `.css` file — same carve-outs as `defaultProjectScopeInclude`
- * (never node_modules, vendored trees, the vgai tooling/engine source, or the editor's
+ * (never node_modules, vendored trees, the volter tooling/engine source, or the editor's
  * own source). Paths are normalized to forward slashes so a Windows dev-id matches. This
  * is the CSS analogue of the `.tsx` stamping scope: an out-of-scope path must not become
  * writable through a client-supplied `file`.
@@ -267,7 +267,7 @@ function sourceResourcePath(file: string, projectRoot: string): string {
   const path = relative(projectRoot, file).replace(/\\/g, '/');
   if (path && path !== '..' && !path.startsWith('../') && !isAbsolute(path)) return path;
   const identity = createHash('sha256').update(file).digest('hex').slice(0, 16);
-  return `.vgai/external-source/${identity}/${basename(file)}`;
+  return `.volter/external-source/${identity}/${basename(file)}`;
 }
 
 /**
@@ -312,7 +312,7 @@ function utilityClassEvidence(dir: string): Map<string, string> {
   }
   // Bounded walk for the css/html entry markers (`@tailwind`, a CDN script):
   // shallow, skipping the directories that never hold a project's own entry.
-  const skip = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.vgai', '.claude']);
+  const skip = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.volter', '.claude']);
   let budget = 80;
   const walk = (current: string, prefix: string, depth: number): void => {
     if (depth > 3 || budget <= 0) return;
@@ -530,7 +530,7 @@ function rejectPendingPropRequests(error: Error): void {
 
 function declaredPropWorker(): Worker {
   if (propWorker) return propWorker;
-  const worker = new Worker(componentPropWorkerUrl(), { name: 'vgai-component-props' });
+  const worker = new Worker(componentPropWorkerUrl(), { name: 'volter-component-props' });
   worker.on(
     'message',
     (message: { id?: unknown; props?: Record<string, ComponentPropSpec[]>; error?: unknown }) => {
@@ -1549,7 +1549,7 @@ export function uiOidPlugin(
     transform(code, id) {
       // A VIRTUAL MODULE IS NOT A FILE, and everything below this line treats
       // `clean` as one — `resolveOidSurface` walks up from it looking for the
-      // owning `vgai.project.json`, and `transformSource` records it as the
+      // owning `volter.project.json`, and `transformSource` records it as the
       // stamped file's path. Vite's convention is that a `\0`-prefixed id was
       // synthesized by a plugin and has no path behind it, so a path plugin
       // skips it.
@@ -1566,7 +1566,7 @@ export function uiOidPlugin(
       // W1 — R3F-dialect files get ` userData-oid` (fiber pierces it into
       // `object.userData.oid`); react-dom files keep ` data-oid` unchanged.
       // WHICH REGION owns this exact file decides: a declaration the project
-      // made (an `include` glob or a `mounts` entry in `vgai.adapter.ts`), the
+      // made (an `include` glob or a `mounts` entry in `volter.adapter.ts`), the
       // manifest root whose `entry` it is, or reach from one through the live
       // import graph. Nothing is inferred from the file's own bytes; a file
       // nothing places gets the documented `data-oid` default, said out loud.
@@ -1688,8 +1688,8 @@ export function uiOidPlugin(
         try {
           const body = await readJson(req);
           const claimedParticipantId = body['participantId'];
-          const trustedParticipantId = req.headers['x-vgai-share-participant-id'];
-          const trustedRole = req.headers['x-vgai-share-role'];
+          const trustedParticipantId = req.headers['x-volter-share-participant-id'];
+          const trustedRole = req.headers['x-volter-share-role'];
           if (
             typeof trustedParticipantId === 'string' &&
             typeof claimedParticipantId === 'string' &&
@@ -1792,10 +1792,10 @@ export function uiOidPlugin(
           const index = currentOidIndex(store, activeProjectRoot(), server);
           res.setHeader('Server-Timing', `index;dur=${Date.now() - indexStarted}`);
           res.setHeader(
-            'X-Vgai-Oid-Index-Enriched',
+            'X-Volter-Oid-Index-Enriched',
             index === lastEnrichedIndex?.index ? '1' : '0',
           );
-          if (typeof req.headers['x-vgai-share-participant-id'] !== 'string') {
+          if (typeof req.headers['x-volter-share-participant-id'] !== 'string') {
             return json(res, index);
           }
           return json(

package/src/source/oid-transform.ts

@@ -1,7 +1,7 @@
 /**
  * OID instrumentation (C1/C2) — the visual-edit "stamp every JSX element with a
- * stable source id" trick, ported to vgai using the TypeScript compiler API
- * (vgai has `typescript`; it does NOT have @babel/*). Hand-authored React UI
+ * stable source id" trick, ported to volter using the TypeScript compiler API
+ * (volter has `typescript`; it does NOT have @babel/*). Hand-authored React UI
  * component source is transformed at build/dev time to carry a `data-oid` on every
  * JSX element, and an OID -> {file,line,col,component,tag} index is built so the
  * editor can map a clicked element back to its exact source location.
@@ -168,7 +168,7 @@ interface SourceEdit {
 const R3F_TRANSFORM_PROPS = ['position', 'rotation', 'scale'] as const;
 
 /**
- * Contracts for components vgai does NOT own, keyed by package specifier and
+ * Contracts for components volter does NOT own, keyed by package specifier and
  * export name. The project resolver reads a local component's contract out of
  * its own source; an installed package has no source to walk from the browser
  * tier and no reason to expect one, so the few whose native root is part of the
@@ -1067,7 +1067,7 @@ export function sourceProvesR3f(evidence: SourceDialectEvidence): boolean {
  *    the HMR half of this same decision, so the two cannot drift apart by hand.
  *
  * 2. **The DEFAULT.** When `surface` is `undefined` — no region placed the
- *    file (an ad-hoc file with no `vgai.project.json` above it, or a module no
+ *    file (an ad-hoc file with no `volter.project.json` above it, or a module no
  *    region's import closure reaches and none declares) — the answer is
  *    `data-oid`, the documented default, and the CALLER says so out loud
  *    (`server/project-root-surface.ts`'s `OID001`/`OID002`). There is
@@ -1075,7 +1075,7 @@ export function sourceProvesR3f(evidence: SourceDialectEvidence): boolean {
  *    for a file it could not place, silently, and being wrong that way is
  *    indistinguishable from being right. Zero inference (ARCHITECTURE-CORE
  *    §The editor protocol) makes the fix a declaration — an `include` glob or
- *    a `mounts` entry in `vgai.adapter.ts` — not a better heuristic.
+ *    a `mounts` entry in `volter.adapter.ts` — not a better heuristic.
  *
  * Nothing about a file's own bytes outranks the region — not even a file that
  * renders THREE host elements while its region says `dom`. That disagreement is
@@ -1209,7 +1209,7 @@ function dreiHtmlLocalNames(sf: ts.SourceFile): Set<string> {
  * `r3f-project-contracts.ts`'s `resolveRelativeModule` already draws between
  * "source this editor walks" and "a dependency it never guesses about".
  *
- * Why the callsite stamp must skip them: `__vgaiOid`/`__vgaiLabel` are a
+ * Why the callsite stamp must skip them: `__volterOid`/`__volterLabel` are a
  * CONTRACT BETWEEN TWO HALVES OF THIS TRANSFORM. The callsite half writes
  * them; the only thing that ever reads them is the callee half —
  * `componentInstanceExpressions` destructuring them out of the component's own
@@ -1223,8 +1223,8 @@ function dreiHtmlLocalNames(sf: ts.SourceFile): Set<string> {
  * MIXED file (an R3F `Scene` and a DOM `Hud` in one module, so the file's one
  * dialect is `userData-oid`), and its `<Canvas>` — `@react-three/fiber`'s own,
  * which spreads its rest props onto the `<div>` it wraps the canvas in — put
- * `__vgaiOid` and `__vgaiLabel` straight into the DOM, for two permanent
- * `React does not recognize the \`__vgaiOid\` prop on a DOM element` errors on
+ * `__volterOid` and `__volterLabel` straight into the DOM, for two permanent
+ * `React does not recognize the \`__volterOid\` prop on a DOM element` errors on
  * every mount of a real game. Nothing was lost by not stamping it, because
  * nothing was reading it.
  *
@@ -1285,7 +1285,7 @@ function dreiCameraLocalNames(sf: ts.SourceFile): Set<string> {
  * tag's callee is unknowable at transform time, and the same hazard as
  * {@link packageImportedLocalNames} for exactly the same reason.
  *
- * `__vgaiOid`/`__vgaiLabel` are a contract between two halves of this
+ * `__volterOid`/`__volterLabel` are a contract between two halves of this
  * transform: the callsite half writes them, the callee half destructures them
  * out of the component's own parameters. A tag bound to a parameter names
  * WHATEVER the caller passed, so this module cannot know whether the callee
@@ -1297,7 +1297,7 @@ function dreiCameraLocalNames(sf: ts.SourceFile): Set<string> {
  * is a parameter — drei's `Stats`/`OrbitControls`, cannon's `Debug`, or a
  * project component, depending on the call) and every R3F `*.stories.tsx`
  * decorator's `<Story />`. Two standing
- * `React does not recognize the \`__vgaiOid\` prop on a DOM element` errors on
+ * `React does not recognize the \`__volterOid\` prop on a DOM element` errors on
  * every run of the acceptance portfolio.
  *
  * Nothing is lost by not stamping, and identity actually IMPROVES: a forwarder
@@ -1437,42 +1437,42 @@ export function transformSource(
       // Default the whole binding. Isolation/preview/bake call a stamped
       // export as a factory (`MainScene()` / `WOOD()`) with no args; a
       // required destructure of `undefined` is `Cannot destructure property
-      // '__vgaiOid'`. React still passes `{}` at a real callsite.
-      sourceEdits.push({ pos: parameters.pos, text: '{ __vgaiOid, __vgaiLabel } = {}' });
-      return { instanceExpression: '__vgaiOid', labelExpression: '__vgaiLabel' };
+      // '__volterOid'`. React still passes `{}` at a real callsite.
+      sourceEdits.push({ pos: parameters.pos, text: '{ __volterOid, __volterLabel } = {}' });
+      return { instanceExpression: '__volterOid', labelExpression: '__volterLabel' };
     }
     if (ts.isObjectBindingPattern(first.name)) {
       sourceEdits.push({
         pos: first.name.getStart(sf) + 1,
-        text: '__vgaiOid, __vgaiLabel, ',
+        text: '__volterOid, __volterLabel, ',
       });
       // After the WHOLE parameter, including a type annotation:
-      // `({ name, ...props }: T)` must become `({ __vgaiOid, …, name, ...props }: T = {})`.
+      // `({ name, ...props }: T)` must become `({ __volterOid, …, name, ...props }: T = {})`.
       // Inserting at the binding's end produced `} = {}: T`, which is not
       // TypeScript and broke every typed scene export the look verb imports.
       if (!first.initializer) {
         sourceEdits.push({ pos: first.getEnd(), text: ' = {}' });
       }
-      return { instanceExpression: '__vgaiOid', labelExpression: '__vgaiLabel' };
+      return { instanceExpression: '__volterOid', labelExpression: '__volterLabel' };
     }
     if (ts.isIdentifier(first.name) && !first.dotDotDotToken) {
       // Preserve the authored identifier as the REST binding. Code below the
       // parameter continues to read `props`, but it now sees only game props:
       // `function Card(props: Props)` becomes
-      // `function Card({ __vgaiOid, __vgaiLabel, ...props }: Props)`.
+      // `function Card({ __volterOid, __volterLabel, ...props }: Props)`.
       // Remove an optional marker while replacing the identifier; a binding
       // pattern cannot itself be optional, so its equivalent is a `{}` default.
       sourceEdits.push({
         pos: first.name.getStart(sf),
         end: first.questionToken?.end ?? first.name.getEnd(),
-        text: `{ __vgaiOid, __vgaiLabel, ...${first.name.text} }`,
+        text: `{ __volterOid, __volterLabel, ...${first.name.text} }`,
       });
       if (!first.initializer) {
         sourceEdits.push({ pos: first.getEnd(), text: ' = {}' });
       }
-      return { instanceExpression: '__vgaiOid', labelExpression: '__vgaiLabel' };
+      return { instanceExpression: '__volterOid', labelExpression: '__volterLabel' };
     }
-    return { instanceExpression: '__vgaiOid', labelExpression: '__vgaiLabel' };
+    return { instanceExpression: '__volterOid', labelExpression: '__volterLabel' };
   };
 
   const pushComponent = (
@@ -1584,7 +1584,7 @@ export function transformSource(
         const element = ts.isJsxOpeningElement(node) ? node.parent : node;
         if (ts.isJsxElement(element) || ts.isJsxSelfClosingElement(element)) {
           // An installed package's module never passes through this transform,
-          // so the callee half of the `__vgaiOid` contract never runs for it and
+          // so the callee half of the `__volterOid` contract never runs for it and
           // the props can only escape (into the DOM, via any package component
           // that spreads its rest props onto a host element). The callsite is
           // still INDEXED above — the source entry, its parent and its contract
@@ -1619,11 +1619,11 @@ export function transformSource(
               : tag;
           const labelAttribute =
             authoredName?.initializer && ts.isJsxExpression(authoredName.initializer)
-              ? `__vgaiLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}`
-              : `__vgaiLabel=${JSON.stringify(label)}`;
+              ? `__volterLabel={${authoredName.initializer.expression?.getText(sf) ?? JSON.stringify(tag)}}`
+              : `__volterLabel=${JSON.stringify(label)}`;
           sourceEdits.push({
             pos: node.attributes.end,
-            text: ` __vgaiOid="${oid}" ${labelAttribute}`,
+            text: ` __volterOid="${oid}" ${labelAttribute}`,
           });
         }
       } else {

package/src/source/plan-csf-story.ts

@@ -188,7 +188,7 @@ export function planDeleteStory(source: string, name: string): CsfStoryPlan {
     return {
       ok: false,
       reason:
-        `'${name}' is this file's declared defaultStory — point vgai.defaultStory at another ` +
+        `'${name}' is this file's declared defaultStory — point volter.defaultStory at another ` +
         'story first',
     };
   }

package/src/source/plan-extract-component.ts

@@ -385,7 +385,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  parameters: { vgai: { default: true } },
+  parameters: { volter: { default: true } },
 };
 `;
 

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/r3f-diagnostic-index.ts

@@ -59,7 +59,7 @@
  * PURELY ADDITIVE. The channel these diagnostics have always had is untouched:
  * `server/project-validation.ts`'s `validateSource` still formats every one of
  * them into the dev server's terminal warning block and into the project
- * warnings map that `/__editor/state` (and so `vgai status`) reports. Rows are
+ * warnings map that `/__editor/state` (and so `volter-game-editor status`) reports. Rows are
  * a second, better-placed audience, not a replacement.
  */
 

package/src/source/r3f-environment-binding.ts

@@ -1,6 +1,6 @@
 /** Exact source tokens for native R3F scene attachments.
  *
- * These are not a VGAI environment format. `<color attach="background">`,
+ * These are not a VOLTER environment format. `<color attach="background">`,
  * `<fog attach="fog">`, and `<fogExp2 attach="fog">` are ordinary Fiber
  * projections of THREE.Scene properties. The live Scene remains runtime truth;
  * this metadata only identifies literal constructor arguments that can be

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

@@ -2,10 +2,10 @@
  * Project-local R3F component contract discovery.
  *
  * This deliberately follows ordinary TypeScript/React modules instead of
- * asking game source to register components with vgai. Relative imports,
+ * asking game source to register components with volter. Relative imports,
  * named/default exports, aliases, and re-exports are enough for the editor to
  * understand the shared-component shape coding models normally produce.
- * External packages remain conservative: vgai never guesses at their runtime
+ * External packages remain conservative: volter never guesses at their runtime
  * scene ownership.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
@@ -419,7 +419,7 @@ export function r3fAuthoringDiagnostics(
       if (
         /^[A-Z]/.test(tag) &&
         contract?.root === 'single' &&
-        // A package component vgai knows only through the built-in table is not
+        // A package component volter knows only through the built-in table is not
         // a hierarchy row of its own — `<RigidBody>` never receives the editor's
         // stamp, so its props are attributed to the node it wraps
         // (`collapsedWrappersOf`). Naming it would name nothing.

package/src/source/writer.ts

@@ -1565,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
@@ -1809,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] ?? '';