@volter/editor-game 0.5.67 → 0.5.69

package/src/host/adapter-reach.ts

@@ -116,7 +116,7 @@ export const CAPTURE_GAP: CapabilityGap = {
  * it as a false alarm and stops trusting the instrument, which is the exact
  * failure this module's header forbids.
  *
- * MEASURED 2026-09-19 on a `--template game` scaffold, standalone `vgai edit`
+ * MEASURED 2026-09-19 on a `--template game` scaffold, standalone `volter-game-editor edit`
  * (it is NOT frame-specific): `hierarchy.roots()` passed, ten `hierarchy
  * .node()` calls passed, and the walk still failed — three of the default
  * scene's nodes report a `parentId` their listed parent does not claim. What

package/src/host/adapter-runtime-bindings.ts

@@ -1,5 +1,5 @@
 /**
- * Installs the loaded `vgai.adapter.ts` runtime bindings onto one mounted
+ * Installs the loaded `volter.adapter.ts` runtime bindings onto one mounted
  * Game. Game modules stay native: adapter closures close over app-owned stores
  * and functions, while this host-side file projects them onto the existing
  * session command/state/input doors.
@@ -188,7 +188,7 @@ function installObservations(
 function actionMap(binding: AdapterInputBinding, game: Game): Map<string, AdapterInputValueType> {
   const actions = binding.actions(game);
   if (!Array.isArray(actions)) {
-    throw new Error('vgai.adapter.ts input.actions must return an array.');
+    throw new Error('volter.adapter.ts input.actions must return an array.');
   }
   const out = new Map<string, AdapterInputValueType>();
   for (const candidate of actions as readonly Partial<AdapterInputAction>[]) {
@@ -198,13 +198,13 @@ function actionMap(binding: AdapterInputBinding, game: Game): Map<string, Adapte
       !ADAPTER_INPUT_VALUE_TYPES.includes(candidate.valueType as AdapterInputValueType)
     ) {
       throw new Error(
-        'vgai.adapter.ts input.actions returned an invalid action; each action needs a non-empty ' +
+        'volter.adapter.ts input.actions returned an invalid action; each action needs a non-empty ' +
           '`name` and a supported `valueType`.',
       );
     }
     if (out.has(candidate.name)) {
       throw new Error(
-        `vgai.adapter.ts input.actions returned duplicate action "${candidate.name}".`,
+        `volter.adapter.ts input.actions returned duplicate action "${candidate.name}".`,
       );
     }
     out.set(candidate.name, candidate.valueType as AdapterInputValueType);
@@ -228,7 +228,7 @@ function valueMatches(type: AdapterInputValueType, value: AdapterInputValue): bo
 function installInput(game: Game, registry: DebugRegistry, binding: AdapterInputBinding): void {
   if (!game.world(binding.root)) {
     throw new Error(
-      `vgai.adapter.ts input.root names "${binding.root}", which is not a mounted manifest root.`,
+      `volter.adapter.ts input.root names "${binding.root}", which is not a mounted manifest root.`,
     );
   }
 

package/src/host/after-paint.ts

@@ -4,13 +4,13 @@
  * READ THIS BEFORE WRITING `requestAnimationFrame` INTO A BOOT PATH.
  * **rAF does not fire in a hidden tab, ever** — not throttled, not late:
  * zero callbacks until the tab is foregrounded. And "hidden at boot" is the
- * ORDINARY case for this editor, not an edge: every `vgai edit` session rooted
+ * ORDINARY case for this editor, not an edge: every `volter-game-editor edit` session rooted
  * in an agent worktree opens its one tab behind the human's window
- * (`server/open-browser.ts` → `open -g`), and any `vgai edit` that fires while
+ * (`server/open-browser.ts` → `open -g`), and any `volter-game-editor edit` that fires while
  * the browser is not frontmost lands the same way. Measured twice in one hour:
  * an editor whose shell mount sat behind a bare double-rAF heartbeat for 20
  * minutes with the relay answering, `document.visibilityState: "hidden"`, and
- * zero console errors, while every `vgai play` refused with "the editor shell
+ * zero console errors, while every `volter-game-editor play` refused with "the editor shell
  * is not bound yet".
  *
  * A paint deferral is only ever an OPTIMISATION — let the committed chrome

package/src/host/api/configurations.ts

@@ -1,7 +1,7 @@
 /**
  * The client half of `/__editor/configurations` (`server/routes/run.ts`): the project's
  * declared run configurations and their runtime status, and the start/stop
- * verbs the transport's picker and `vgai run` share.
+ * verbs the transport's picker uses.
  */
 
 import { assertEditorServerResponse, editorServerJson } from '@volter/editor-sdk/kit/editor-server-response';

package/src/host/authoring/canvas-runtime-recognition.ts

@@ -22,7 +22,7 @@ export interface PhaserRealmLike {
 export interface BabylonRealmLike {
   BABYLON?: { Engine?: { Instances?: BabylonEngineLike[] } };
   /** Host build seam for module-bundled Babylon, where no BABYLON global exists. */
-  __vgaiBabylon?: {
+  __volterBabylon?: {
     engines?: BabylonEngineLike[];
     /** Optional boot promise published by a host-built classic bundle. */
     ready?: PromiseLike<unknown>;
@@ -39,7 +39,7 @@ export function findPhaserGame(realm: PhaserRealmLike | null): PhaserGameLike |
 
 /** Recognize Babylon from its public engine registry or the module-build host seam. */
 export function findBabylonEngine(realm: BabylonRealmLike | null): BabylonEngineLike | null {
-  const bridged = realm?.__vgaiBabylon?.engines;
+  const bridged = realm?.__volterBabylon?.engines;
   const engines = Array.isArray(bridged) ? bridged : realm?.BABYLON?.Engine?.Instances;
   if (!Array.isArray(engines)) return null;
   return (

package/src/host/authoring/contract-hierarchy-authoring.ts

@@ -8,8 +8,8 @@
 
 import type { AuthoringAdapter, EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
 import type {
-  VgaiGameHierarchyGroup,
-  VgaiGameHierarchyProvider,
+  VolterGameHierarchyGroup,
+  VolterGameHierarchyProvider,
 } from '@volter/editor-project/adapter/ingest/game-contract';
 import { editorConsole } from '@volter/editor-sdk/kit/editor-console';
 
@@ -20,7 +20,7 @@ function groupNodeId(id: string): string {
   return `${GROUP_PREFIX}${encodeURIComponent(id)}`;
 }
 
-function groupNode(group: VgaiGameHierarchyGroup): EditorNode {
+function groupNode(group: VolterGameHierarchyGroup): EditorNode {
   return {
     id: groupNodeId(group.id),
     label: group.label,
@@ -32,7 +32,7 @@ function groupNode(group: VgaiGameHierarchyGroup): EditorNode {
   };
 }
 
-function assertGroups(value: unknown): VgaiGameHierarchyGroup[] {
+function assertGroups(value: unknown): VolterGameHierarchyGroup[] {
   if (!Array.isArray(value)) throw new Error('hierarchy() did not return an array');
   const ids = new Set<string>();
   for (const group of value) {
@@ -58,12 +58,12 @@ function assertGroups(value: unknown): VgaiGameHierarchyGroup[] {
 /** Identity-preserving when the game declares no hierarchy surface. */
 export function withContractHierarchy(
   base: AuthoringAdapter,
-  provider: VgaiGameHierarchyProvider | undefined,
+  provider: VolterGameHierarchyProvider | undefined,
 ): AuthoringAdapter {
   if (!provider) return base;
 
   let warned = false;
-  const groups = (): VgaiGameHierarchyGroup[] => {
+  const groups = (): VolterGameHierarchyGroup[] => {
     try {
       return assertGroups(provider());
     } catch (error) {

package/src/host/authoring/contract-scenes-stories.ts

@@ -1,5 +1,5 @@
 /**
- * Projects an ingested game's declared SCENES (`window.vgaiGame.scenes`, see
+ * Projects an ingested game's declared SCENES (`window.volterGame.scenes`, see
  * `@volter/editor-project/adapter/ingest/game-contract`) onto the ordinary
  * {@link StoriesProvider} the editor's story picker already reads — the sibling
  * of `contract-hierarchy-authoring.ts`, which does the same job for the
@@ -29,11 +29,11 @@ import type {
   LiveSceneTable,
 } from '@volter/editor-sdk/host';
 import type { StoriesProvider, StoryRef } from '@volter/editor-project/adapter';
-import type { VgaiGameContract, VgaiGameScene } from '@volter/editor-project/adapter/ingest/game-contract';
+import type { VolterGameContract, VolterGameScene } from '@volter/editor-project/adapter/ingest/game-contract';
 import { readGameScenes } from '@volter/editor-project/adapter/ingest/game-contract';
 import { editorConsole } from '@volter/editor-sdk/kit/editor-console';
 
-function assertScenes(value: unknown): VgaiGameScene[] {
+function assertScenes(value: unknown): VolterGameScene[] {
   if (!Array.isArray(value)) throw new Error('scenes.list() did not return an array');
   const ids = new Set<string>();
   for (const scene of value) {
@@ -111,7 +111,7 @@ export interface ContractScenesSeams {
  * bound: `readGameScenes` owns that shape check.
  */
 export function createContractScenesStories(
-  contract: VgaiGameContract | null | undefined,
+  contract: VolterGameContract | null | undefined,
   seams: ContractScenesSeams = {},
 ): ContractScenesStories | null {
   const { scenes, malformed } = readGameScenes(contract);
@@ -121,7 +121,7 @@ export function createContractScenesStories(
   if (!scenes) return null;
 
   let warned = false;
-  const list = (): VgaiGameScene[] => {
+  const list = (): VolterGameScene[] => {
     try {
       return assertScenes(scenes.list());
     } catch (error) {

package/src/host/authoring/ingest-data-writer.ts

@@ -53,7 +53,7 @@ import type { ChannelValue } from '@volter/editor-sdk/kit/creation-site-edit';
  * that carries none: that object is unanchored, with its reason, and its edits
  * stay live-only (the anti-shim rule).
  */
-export const DATA_RECORD_KEY = 'vgaiRecordIndex';
+export const DATA_RECORD_KEY = 'volterRecordIndex';
 
 /** The record index a live object declares, or `null` when it declares none. */
 export function dataRecordIndexOf(object: unknown): number | null {

package/src/host/authoring/ingest-source-persistence.ts

@@ -772,7 +772,7 @@ export class IngestSourcePersistence {
     const history = this.history!;
     const descriptor = history.registry.registerProject(
       'overlay',
-      '.vgai/ingest-live-objects',
+      '.volter/ingest-live-objects',
       'Ingested game objects',
     );
     const driver: ResourceDriver = {
@@ -813,7 +813,7 @@ export class IngestSourcePersistence {
 /**
  * Report a refusal where the user can see it, once per gesture.
  *
- * A WARNING, not a log line, because of where each one goes: `vgai status`
+ * A WARNING, not a log line, because of where each one goes: `volter-game-editor status`
  * surfaces `sessionWarnings` and shows nothing at all for `log`. A refused
  * write was invisible to every door the product has — the user's edit did not
  * reach their file and the only explanation lived in a panel nobody could read

package/src/host/authoring/mount-isolated-pixi-screen.ts

@@ -148,7 +148,7 @@ export async function mountIsolatedPixiScreen(
     preserveDrawingBuffer: true,
   });
   const canvas = app.canvas as HTMLCanvasElement;
-  canvas.dataset['vgaiCanvasSceneSurface'] = 'true';
+  canvas.dataset['volterCanvasSceneSurface'] = 'true';
   canvas.style.position = 'absolute';
   canvas.style.inset = '0';
   canvas.style.width = '100%';

package/src/host/authoring/pixi-authoring-adapter.ts

@@ -82,8 +82,10 @@ import {
   readContainerAuthoringLabel,
 } from './pixi-source-identity';
 import { CanvasStructureHistory } from './pixi-structure-history';
+import { PIXI_CREATABLE_KINDS } from './pixi-creatable-kinds';
 import { fromNeutralTransform, toNeutralTransform } from './pixi-transform-channels';
 import { resolvesLiveOnly, runWritePipe } from '@volter/editor-sdk/kit/write-pipe';
+import { editorHost } from '@volter/editor-sdk/host';
 
 /**
  * What a write target is handed at construction — the live view it edits
@@ -245,7 +247,7 @@ export interface PixiAuthoringOptions {
    * `pickable` at all — a stage with no mapped surface cannot answer where a
    * client point landed, and guessing one would fabricate a hit.
    *
-   * When the element carries `data-vgai-stage-width`/`-height`, those are the
+   * When the element carries `data-volter-stage-width`/`-height`, those are the
    * stage's LOGICAL size and the mapping divides the measured rect by them —
    * which is what lets a design surface presented through the shared pan/zoom
    * camera (a CSS scale) pick correctly. Without them the mapping is 1:1,
@@ -302,12 +304,19 @@ export interface PixiAuthoringOptions {
  * `Texture.WHITE` and a size; a graphics gets a drawn rect): a node the author
  * cannot see is indistinguishable from a create that silently failed.
  */
-const CANVAS_CREATABLE_KINDS: readonly { kind: string; label: string }[] = [
-  { kind: 'container', label: 'Container' },
-  { kind: 'sprite', label: 'Sprite' },
-  { kind: 'text', label: 'Text' },
-  { kind: 'graphics', label: 'Graphics' },
-];
+/** The project-local section holding each canvas world's locked and grouped label paths. */
+const EDIT_LOCKS_SECTION = 'canvasEditLocks';
+type EditLocks = Record<string, { readonly locked: readonly string[]; readonly grouped: readonly string[] }>;
+
+function readEditLocks(): EditLocks {
+  return editorHost().projectLocalState.read<EditLocks>(EDIT_LOCKS_SECTION) ?? {};
+}
+
+function writeEditLocks(world: string, locks: EditLocks[string]): void {
+  editorHost().projectLocalState.write(EDIT_LOCKS_SECTION, { ...readEditLocks(), [world]: locks });
+}
+
+const CANVAS_CREATABLE_KINDS = PIXI_CREATABLE_KINDS;
 
 /** What a canvas world can take from the asset browser: an image becomes a
  *  Sprite. A model or an audio file has no display object to become here. */
@@ -404,6 +413,11 @@ function defaultLabelFor(kind: string): string {
  *  `pixi` is THIS SURFACE's namespace ({@link PixiAuthoringOptions.pixi}): a
  *  node built from another graph's classes is a foreign object in the world's
  *  own display list, and the world's renderer is the one that has to draw it. */
+/** A ParticleContainer, from whichever copy of Pixi made it: it adds particles, never children. */
+function isParticleContainer(object: Container | null | undefined): boolean {
+  return !!object && typeof (object as { addParticle?: unknown }).addParticle === 'function';
+}
+
 function createDisplayObject(pixi: CanvasPixiNamespace, kind: string): Container | null {
   switch (kind) {
     case 'container':
@@ -417,6 +431,31 @@ function createDisplayObject(pixi: CanvasPixiNamespace, kind: string): Container
       return new pixi.Text({ text: 'Text', style: { fill: 0xffffff, fontSize: 24 } });
     case 'graphics':
       return new pixi.Graphics().rect(0, 0, 100, 100).fill(0xffffff);
+    case 'animatedSprite': {
+      const animated = new pixi.AnimatedSprite([pixi.Texture.WHITE]);
+      animated.setSize(64, 64);
+      return animated;
+    }
+    case 'tilingSprite':
+      return new pixi.TilingSprite({ texture: pixi.Texture.WHITE, width: 100, height: 100 });
+    case 'nineSliceSprite':
+      return new pixi.NineSliceSprite({ texture: pixi.Texture.WHITE, width: 100, height: 100 });
+    case 'bitmapText':
+      return new pixi.BitmapText({ text: 'BitmapText', style: { fill: 0xffffff, fontSize: 24 } });
+    case 'htmlText':
+      return new pixi.HTMLText({ text: 'HTMLText', style: { fill: 0xffffff, fontSize: 24 } });
+    case 'meshPlane': {
+      const plane = new pixi.MeshPlane({ texture: pixi.Texture.WHITE });
+      plane.setSize(100, 100);
+      return plane;
+    }
+    case 'perspectiveMesh': {
+      const mesh = new pixi.PerspectiveMesh({ texture: pixi.Texture.WHITE });
+      mesh.setSize(100, 100);
+      return mesh;
+    }
+    case 'particleContainer':
+      return new pixi.ParticleContainer();
     default:
       return null;
   }
@@ -490,6 +529,35 @@ interface CanvasBoxEditSession {
   readonly id: string;
   readonly transform: Transform;
   readonly rect: { x: number; y: number; width: number; height: number };
+  /** The parent's world matrix's linear part (Pixi's a, b, c, d), when the node has a parent. */
+  readonly parentLinear?: { a: number; b: number; c: number; d: number };
+}
+
+/**
+ * The local turn, in degrees, that turns the node's own x axis by `degrees` on screen. Godot measures
+ * a rotate drag in the parent's space; a turn added straight to the local rotation goes backwards
+ * under a mirrored parent and by the wrong amount under an unevenly scaled one.
+ */
+function localTurn(session: CanvasBoxEditSession, degrees: number): number {
+  const m = session.parentLinear;
+  if (!m) return degrees;
+  const det = m.a * m.d - m.b * m.c;
+  if (Math.abs(det) < 1e-9) return degrees;
+  const [, , z, w] = session.transform.rotation;
+  const r = 2 * Math.atan2(z, w);
+  // The node's x axis on screen, turned by the drag, taken back into the parent's space.
+  const vx = m.a * Math.cos(r) + m.c * Math.sin(r);
+  const vy = m.b * Math.cos(r) + m.d * Math.sin(r);
+  const t = (degrees * Math.PI) / 180;
+  const wx = vx * Math.cos(t) - vy * Math.sin(t);
+  const wy = vx * Math.sin(t) + vy * Math.cos(t);
+  const ux = (m.d * wx - m.c * wy) / det;
+  const uy = (-m.b * wx + m.a * wy) / det;
+  // A long drag passes half a turn: keep the answer beside the turn's own direction in that space.
+  const base = det < 0 ? -t : t;
+  const raw = Math.atan2(uy, ux) - r - base;
+  const wrapped = Math.atan2(Math.sin(raw), Math.cos(raw));
+  return ((base + wrapped) * 180) / Math.PI;
 }
 
 function boxPatchChannels(patch: Record<string, number>): TransformChannel[] {
@@ -538,7 +606,18 @@ function transformForBoxPatch(
     scale: [...session.transform.scale],
   };
   const rotate = patch['rotate'];
-  if (rotate !== undefined) next.rotation = rotateTransformZ(session.transform, rotate);
+  if (rotate !== undefined) {
+    let turn = localTurn(session, rotate);
+    const step = patch['rotationStep'];
+    if (step !== undefined && step > 0) {
+      // Configure Snap's absolute step lands the node's own rotation on the step from the offset.
+      const [, , z, w] = session.transform.rotation;
+      const start = (2 * Math.atan2(z, w) * 180) / Math.PI;
+      const offset = patch['rotationOffset'] ?? 0;
+      turn = Math.round((start + turn - offset) / step) * step + offset - start;
+    }
+    next.rotation = rotateTransformZ(session.transform, turn);
+  }
   const width = patch['width'];
   if (width !== undefined && session.rect.width > 0) {
     next.scale[0] = session.transform.scale[0] * Math.max(0.0001, width / session.rect.width);
@@ -669,10 +748,17 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
     | undefined;
   private listeners = new Set<() => void>();
   private boxEditSessions = new Map<string, CanvasBoxEditSession>();
-  private lockedIds = new Set<string>();
-  /** Godot's Group: a click on any node inside a grouped one selects the group. Session-local, as
-   *  the lock is. */
-  private groupedIds = new Set<string>();
+  /**
+   * Lock (a click passes through the node) and Godot's Group (a click inside a grouped node selects
+   * the group), held by each node's label path in this world so they survive the remount a source
+   * write causes and the next session. Kept per checkout, as Unity keeps scene pickability per
+   * user; Godot writes them into the scene file instead.
+   */
+  private lockedPaths = new Set<string>();
+  private groupedPaths = new Set<string>();
+  private readonly editLockWorld: string;
+  /** Each node's label path, cleared whenever the tree is re-projected. */
+  private pathKeys = new Map<string, string>();
 
   constructor(
     private readonly root: Container,
@@ -728,8 +814,10 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
           const hit = this.projector.pick(clientX, clientY, (id) => this.isPickLocked(id));
           return hit ? this.groupOf(hit) : hit;
         },
-        candidates: (clientX, clientY) =>
-          this.projector.candidates(clientX, clientY, (id) => this.isPickLocked(id)),
+        candidates: (clientX, clientY, options) =>
+          this.projector.candidates(clientX, clientY, (id) =>
+            options?.includeLocked ? false : this.isPickLocked(id),
+          ),
       };
       this.rects = {
         rect: (id) => this.projector.rect(id),
@@ -750,7 +838,46 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
         this.target.provenance.source === 'source-code' && this.target.persistence !== undefined,
     };
     this.target.bind({ a2d: this.a2d, store, journal: opts.journal, notify: () => this.notify() });
-    this.structure = this.target.structure ?? this.liveStructure;
+    this.editLockWorld = opts.journal.id;
+    const saved = readEditLocks()[this.editLockWorld];
+    this.lockedPaths = new Set(saved?.locked ?? []);
+    this.groupedPaths = new Set(saved?.grouped ?? []);
+    const structure = this.target.structure ?? this.liveStructure;
+    // A placed creation reaches the structure in the new node's PARENT's own space: the target
+    // writes `x`/`y` as authored, and only this adapter knows the frame `rects` answer in.
+    // A ParticleContainer holds particles its code adds, never display objects: Pixi's `addChild`
+    // on one throws, so nothing is created or moved into it.
+    const holdsNoChildren = (parentId: string | null | undefined): boolean =>
+      !!parentId && isParticleContainer(this.projector.object(parentId));
+    const noChildren = 'a ParticleContainer holds particles added with addParticle, not display objects.';
+    this.structure = {
+      ...structure,
+      create: (kind, parentId, at) =>
+        holdsNoChildren(parentId)
+          ? { id: '', ack: this.refuseStructure(noChildren) }
+          : structure.create(kind, parentId, at ? this.pointInParent(parentId ?? null, at) : undefined),
+      ...(structure.reparent
+        ? {
+            reparent: (id: string, newParentId: string | null) =>
+              holdsNoChildren(newParentId) ? this.refuseStructure(noChildren) : structure.reparent!(id, newParentId),
+          }
+        : {}),
+      ...(structure.paste
+        ? {
+            paste: (parentId: string | null) =>
+              holdsNoChildren(parentId) ? this.refuseStructure(noChildren) : structure.paste!(parentId),
+          }
+        : {}),
+      ...(structure.canPaste
+        ? { canPaste: (parentId: string | null) => !holdsNoChildren(parentId) && structure.canPaste!(parentId) }
+        : {}),
+      ...(structure.creatableKinds
+        ? {
+            creatableKinds: (parentId: string | null) =>
+              holdsNoChildren(parentId) ? [] : structure.creatableKinds!(parentId),
+          }
+        : {}),
+    };
     this.assetDrop =
       this.target.assetDrop ??
       ({
@@ -851,6 +978,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
     queueMicrotask(() => {
       this.structureNotifyQueued = false;
       this.projector.reproject();
+      this.pathKeys.clear();
       this.watchStructure(this.root);
       this.target.onReindex();
       this.notify();
@@ -951,7 +1079,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
   // degrade — a half-answer would be a menu item that silently does nothing.
 
   private readonly liveStructure: StructureProvider = {
-    create: (kind, parentId) => this.createStructuralNode(kind, parentId ?? null),
+    create: (kind, parentId, at) => this.createStructuralNode(kind, parentId ?? null, at),
     remove: (id) => this.removeStructuralNodes([id]),
     removeMany: (ids) => this.removeStructuralNodes(ids),
     duplicate: (id) => this.duplicateStructuralNode(id),
@@ -967,7 +1095,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
   private containerFor(parentId: string | null): Container | null {
     if (!parentId) return this.root;
     const object = this.projector.object(parentId);
-    if (!object || typeof object.addChild !== 'function') return null;
+    if (!object || typeof object.addChild !== 'function' || isParticleContainer(object)) return null;
     return object;
   }
 
@@ -1015,6 +1143,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
    */
   private afterStructuralChange(): void {
     this.projector.reproject();
+    this.pathKeys.clear();
     this.watchStructure(this.root);
     this.target.onReindex();
     this.notify();
@@ -1031,7 +1160,22 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
    * same turn. The live-only report is the other half of the answer and rides
    * back in `ack` (see `StructuralIdWrite`) instead of being fired `void`.
    */
-  private createStructuralNode(kind: string, parentId: string | null): StructuralIdWrite {
+  /** A point in the `rects` frame, in the space of the container a new child of `parentId` joins. */
+  private pointInParent(
+    parentId: string | null,
+    at: { readonly x: number; readonly y: number },
+  ): { x: number; y: number } | undefined {
+    const parent = this.containerFor(parentId);
+    if (!parent || typeof parent.updateLocalTransform !== 'function') return undefined;
+    const local = this.localToRootMatrix(parent).clone().invert().apply({ x: at.x, y: at.y });
+    return { x: local.x, y: local.y };
+  }
+
+  private createStructuralNode(
+    kind: string,
+    parentId: string | null,
+    at?: { readonly x: number; readonly y: number },
+  ): StructuralIdWrite {
     const parent = this.containerFor(parentId);
     if (!parent) {
       return {
@@ -1047,6 +1191,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
       };
     }
     node.label = defaultLabelFor(kind);
+    if (at) node.position.set(at.x, at.y);
     const label = `Create ${node.label}`;
     this.structureHistory.track(parent);
     this.structureHistory.track(node);
@@ -1280,7 +1425,13 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
         this.boxEditSessions.delete(id);
         return;
       }
-      this.boxEditSessions.set(id, { id, rect, transform: this.transforms.get(id) });
+      const parent = this.projector.object(id)?.parent?.worldTransform;
+      this.boxEditSessions.set(id, {
+        id,
+        rect,
+        transform: this.transforms.get(id),
+        ...(parent ? { parentLinear: { a: parent.a, b: parent.b, c: parent.c, d: parent.d } } : {}),
+      });
       this.transforms.beginEdit?.(id);
     },
     apply: (id, patch) => this.applyBoxEdit(id, patch),
@@ -1514,15 +1665,19 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
     ],
     get: (id, path) =>
       path === 'locked'
-        ? this.lockedIds.has(id)
+        ? this.lockedPaths.has(this.pathKeyOf(id))
         : path === 'grouped'
-          ? this.groupedIds.has(id)
+          ? this.groupedPaths.has(this.pathKeyOf(id))
           : this.target.get(id, path),
     set: (id, path, value) => {
       if (path === 'locked' || path === 'grouped') {
-        const set = path === 'locked' ? this.lockedIds : this.groupedIds;
-        if (value === true) set.add(id);
-        else set.delete(id);
+        const set = path === 'locked' ? this.lockedPaths : this.groupedPaths;
+        if (value === true) set.add(this.pathKeyOf(id));
+        else set.delete(this.pathKeyOf(id));
+        writeEditLocks(this.editLockWorld, {
+          locked: [...this.lockedPaths],
+          grouped: [...this.groupedPaths],
+        });
         this.notify();
         return;
       }
@@ -1532,12 +1687,36 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
     remove: (id, path) => this.target.remove?.(id, path),
   };
 
+  /** `id`'s label path from its world's root: each step the authored label and its place among
+   *  same-labelled siblings, so it holds across line edits and reloads (a rename drops it). */
+  private pathKeyOf(id: string): string {
+    const known = this.pathKeys.get(id);
+    if (known !== undefined) return known;
+    const labelOf = (nodeId: string): string => this.projector.object(nodeId)?.label ?? '';
+    const segments: string[] = [];
+    let current: string | null = id;
+    while (current) {
+      const node = this.projector.node(current);
+      if (!node) break;
+      const siblings = node.parentId
+        ? (this.projector.node(node.parentId)?.childIds ?? [])
+        : this.projector.roots().map((root) => root.id);
+      const label = labelOf(current);
+      const place = siblings.filter((sibling) => labelOf(sibling) === label).indexOf(current);
+      segments.unshift(`${label}#${Math.max(0, place)}`);
+      current = node.parentId ?? null;
+    }
+    const key = segments.join('/');
+    this.pathKeys.set(id, key);
+    return key;
+  }
+
   /** The outermost grouped node that contains `id`, or `id` itself when none does. */
   private groupOf(id: string): string {
     let group = id;
     let current: string | null = id;
     while (current) {
-      if (this.groupedIds.has(current)) group = current;
+      if (this.groupedPaths.has(this.pathKeyOf(current))) group = current;
       current = this.projector.node(current)?.parentId ?? null;
     }
     return group;
@@ -1546,7 +1725,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
   private isPickLocked(id: string): boolean {
     let current: string | null = id;
     while (current) {
-      if (this.lockedIds.has(current)) return true;
+      if (this.lockedPaths.has(this.pathKeyOf(current))) return true;
       current = this.projector.node(current)?.parentId ?? null;
     }
     return false;
@@ -1565,8 +1744,7 @@ export class PixiAuthoringAdapter implements AuthoringAdapter {
 
   dispose(): void {
     this.boxEditSessions.clear();
-    this.lockedIds.clear();
-    this.groupedIds.clear();
+    this.pathKeys.clear();
     for (const object of this.watchedForStructure) {
       object.off('childAdded', this.onStructureChanged);
       object.off('childRemoved', this.onStructureChanged);