@volter/editor-game 0.5.65

package/src/host/authoring/pixi-source-identity.ts

@@ -0,0 +1,141 @@
+/**
+ * The OID half of the canvas authoring surface's IDENTITY axis
+ * (`@volter/game-runtime/pixi/authoring`'s {@link CanvasIdentity}) — what a row is called
+ * when the display tree was authored as first-party `@pixi/react` TSX, and the
+ * resolution from such an id back to the source tag it addresses.
+ *
+ * Pure: no Pixi mount, no network, so both halves are unit-testable directly
+ * (`packages/editor/test/pixi-source-identity.test.ts`). The structural half of
+ * the same axis is `STRUCTURAL_CANVAS_IDENTITY`, in the engine beside the walk
+ * it parameterizes.
+ *
+ * ## Where the address comes from (MEASURED, not assumed)
+ *
+ * A canvas `.tsx` is stamped `data-oid` by the same transform every dom file
+ * gets (`ui-source/oid-transform.ts`'s `oidAttributeForSurface`: a `canvas`
+ * declared surface returns `data-oid`). `@pixi/react` hands every unrecognized
+ * prop to the Pixi class CONSTRUCTOR (`createInstance` → `new
+ * PixiComponent(pixiProps)`), and Pixi assigns its options onto the instance —
+ * so the stamp lands on the live `Container` under its own literal key,
+ * `container['data-oid']`.
+ *
+ * That is a fact about `@pixi/react`, not about this repo, and it is pinned by
+ * a real mount rather than reasoned about: `packages/editor/test/
+ * pixi-oid-stamp.test.tsx` mounts the real reconciler and asserts it. (The
+ * plausible-looking alternative — that the dash is PIERCED to `container.oid`
+ * the way fiber pierces `userData-oid` — is what this module was first written
+ * against, and the mount test is what caught it: every row silently fell back
+ * to a structural path.) {@link readContainerOid} is the ONE place that
+ * knows.
+ *
+ * Ids follow the three lane's `r3f:<worldId>:<oid>` precedent
+ * (`r3f-source-authoring-adapter.ts`) with a `pixi:` prefix, and they exist for
+ * that lane's reason: an oid signature is stable across a remount, so
+ * selection survives one.
+ */
+
+import type { CanvasIdentity } from '@volter/game-runtime/pixi/authoring';
+import type { Container } from 'pixi.js';
+import { occurrenceId } from '@volter/editor-core/authoring/component-instance-root';
+
+const PREFIX = 'pixi';
+
+/** The live field the `data-oid` JSX prop becomes — see this module's header.
+ *  Spelled once, here. */
+const OID_FIELD = 'data-oid';
+const INSTANCE_FIELD = 'data-authoring-instance';
+const INSTANCE_LABEL_FIELD = 'data-authoring-label';
+const INSTANCE_COMPONENT_FIELD = 'data-authoring-component';
+
+/**
+ * The oid `@pixi/react` landed on a live display object, or `undefined`.
+ *
+ * Deliberately structural (`typeof === 'string'`): a game's own container
+ * subclass may declare an unrelated `oid` field, and a non-string one is not
+ * an address.
+ */
+export function readContainerOid(object: unknown): string | undefined {
+  if (!object || typeof object !== 'object') return undefined;
+  const value = (object as Record<string, unknown>)[OID_FIELD];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function stringField(object: unknown, field: string): string | undefined {
+  if (!object || typeof object !== 'object') return undefined;
+  const value = (object as Record<string, unknown>)[field];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export function readContainerAuthoringInstance(object: unknown): string | undefined {
+  return stringField(object, INSTANCE_FIELD);
+}
+
+export function readContainerAuthoringLabel(object: unknown): string | undefined {
+  return stringField(object, INSTANCE_LABEL_FIELD);
+}
+
+export function readContainerAuthoringComponent(object: unknown): string | undefined {
+  return stringField(object, INSTANCE_COMPONENT_FIELD);
+}
+
+/** The first native Pixi host emitted by a component instance. */
+export function isCanvasComponentInstanceRoot(object: Container): boolean {
+  const instance = readContainerAuthoringInstance(object);
+  if (!instance) return false;
+  return readContainerAuthoringInstance(object.parent) !== instance;
+}
+
+/** Callsite OID for a component root, otherwise the element's own OID. */
+export function authoringOidForContainer(object: Container): string | undefined {
+  return isCanvasComponentInstanceRoot(object)
+    ? readContainerAuthoringInstance(object)
+    : readContainerOid(object);
+}
+
+/** `pixi:<worldId>:<oid>`, with `#n` for every occurrence past the first. */
+export function pixiOidId(worldId: string, oid: string, occurrence = 0): string {
+  return occurrenceId(`${PREFIX}:${worldId}:${oid}`, occurrence);
+}
+
+/** The address for a node the source never stamped — an object the game built
+ *  imperatively, or a library's internal child. Structural, so it is stable
+ *  for as long as the tree's shape is. */
+export function pixiPathId(worldId: string, path: readonly number[]): string {
+  return `${PREFIX}:${worldId}:@${path.join('.')}`;
+}
+
+/** The oid an id addresses, or `null` for a path id / an id minted for a
+ *  DIFFERENT world. Never guesses. */
+export function oidOfPixiId(worldId: string, id: string): string | null {
+  const head = `${PREFIX}:${worldId}:`;
+  if (!id.startsWith(head)) return null;
+  const rest = id.slice(head.length);
+  if (rest.startsWith('@')) return null;
+  const hash = rest.indexOf('#');
+  const oid = hash < 0 ? rest : rest.slice(0, hash);
+  return oid.length > 0 ? oid : null;
+}
+
+/**
+ * The identity a FIRST-PARTY canvas root supplies to the shared walk.
+ *
+ * A repeated callsite (`sim.grunts.map(…)` renders one JSX element ninety
+ * times) resolves ninety live objects to one oid; they are disambiguated with
+ * the same `#n` occurrence suffix the three lane uses, counted per walk — which
+ * is what {@link CanvasIdentity.beginWalk} exists for.
+ */
+export function createOidCanvasIdentity(worldId: string): CanvasIdentity {
+  let occurrences = new Map<string, number>();
+  return {
+    beginWalk: () => {
+      occurrences = new Map();
+    },
+    idFor: (object: Container, path: readonly number[]): string => {
+      const oid = authoringOidForContainer(object);
+      if (oid === undefined) return pixiPathId(worldId, path);
+      const n = occurrences.get(oid) ?? 0;
+      occurrences.set(oid, n + 1);
+      return pixiOidId(worldId, oid, n);
+    },
+  };
+}

package/src/host/authoring/pixi-still-presentation.ts

@@ -0,0 +1,71 @@
+/**
+ * STILL-STAGE PRESENTATION for design-time Pixi mounts — the two pieces the
+ * canvas design layer (`canvas-design-mount.ts`) and the isolated screen mount
+ * (`mount-isolated-pixi-screen.ts`) each spelled for themselves (owner-directed
+ * overlap audit, 2026-08-22): framing authored bounds into the Scene camera,
+ * and preparing a camera-presented frame for capture on a hidden tab.
+ *
+ * Both mounts share one presentation model: the stage is STILL (no ticker —
+ * Edit's paused clock), the editor camera owns pan/zoom, and a capture must
+ * see the exact camera-presented frame rather than a raw-stage extraction.
+ * What stays per-mount is the render itself (whose renderer, whose stage,
+ * whose camera pose) — handed in as `renderScene`.
+ */
+
+import { registerPresentedCanvasFrame } from '@volter/editor-core/canvas-preview-frames';
+import type { RootViewController } from '@volter/editor-core/authoring/world-pan-state';
+
+/**
+ * Frame authored world bounds in the independent Scene camera. Unlike an
+ * asset/UI preview, a scene editor may magnify small subjects: zoom is an
+ * inspection tool, not a claim about the runtime's pixel scale. `false` when
+ * the pane or the bounds are too small to frame yet (a sub-2px pane is a
+ * dock mid-layout, not a viewport).
+ */
+export function fitSceneView(
+  layer: HTMLElement,
+  bounds: { x: number; y: number; width: number; height: number },
+  view: RootViewController,
+  /** A floor on the zoom the fit may choose — the OPENING fit passes the zoom
+   *  that frames the game's declared resolution, so a world whose floor dwarfs
+   *  its actors still opens at the scale the player sees (see the mount). */
+  minZoom = 0.1,
+): boolean {
+  const rect = layer.getBoundingClientRect();
+  if (rect.width < 2 || rect.height < 2) return false;
+  if (!(bounds.width > 0) || !(bounds.height > 0)) return false;
+  const zoom = Math.min(
+    4,
+    Math.max(
+      minZoom,
+      Math.min((rect.width - 96) / bounds.width, (rect.height - 96) / bounds.height),
+    ),
+  );
+  view.setView(
+    rect.width / 2 - (bounds.x + bounds.width / 2) * zoom,
+    rect.height / 2 - (bounds.y + bounds.height / 2) * zoom,
+    zoom,
+  );
+  return true;
+}
+
+/**
+ * A hidden editor tab has no rAF, but capture is still a first-class reader of
+ * the authoring surface. Register a presenter that prepares the exact
+ * camera-presented frame at that boundary instead of falling back to raw-stage
+ * extraction: `renderScene` is retried across event-loop turns because the
+ * first frames of a mount can race layout (`false` = not renderable yet).
+ * Returns the unregister function.
+ */
+export function registerStillFramePresenter(
+  canvas: HTMLCanvasElement,
+  renderScene: () => boolean,
+): () => void {
+  return registerPresentedCanvasFrame(canvas, async () => {
+    for (let turn = 0; turn < 24; turn++) {
+      if (renderScene()) return null;
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    }
+    return null;
+  });
+}

package/src/host/authoring/pixi-structure-history.ts

@@ -0,0 +1,237 @@
+/**
+ * ONE undo entry per STRUCTURAL op on a live canvas tree — the bracket
+ * `PixiAuthoringAdapter.structure` wraps every create/remove/duplicate/
+ * reparent/reorder in.
+ *
+ * It is the SAME history path a transform edit already takes (a
+ * {@link JsonHistoryResource} registered against `store.projectHistory`), not a
+ * second one: what differs is the STATE SHAPE, and that is why it is a resource
+ * of its own rather than a field bolted onto the write target's. The write
+ * target journals a node's VALUES (label, alpha, tint, transform) keyed by the
+ * adapter's structural-path id; a structural op changes what those ids even
+ * ARE, so a value snapshot cannot describe it. This resource journals
+ * PLACEMENTS instead — "which parent, at which index, in which local pose" —
+ * keyed by a uid stamped on the display object itself, which survives the
+ * re-walk that renames every id.
+ *
+ * WHY A UID AND A REGISTRY. A removed object must be resurrectable, so it is
+ * kept alive here (detached, never `destroy()`ed) and found again by uid; a
+ * JSON snapshot cannot hold a `Container` reference. The registry is the ONLY
+ * thing that makes undo-of-remove possible at all.
+ *
+ * IT IS DELIBERATELY EDIT-SCOPED. Only objects an editor op touched (plus the
+ * ancestors those ops named) are tracked, so a restore never reorders the
+ * thousands of sprites a RUNNING game adds and removes on its own every frame.
+ * For the same reason `conflictIdentity` narrows to the parent map: a game that
+ * appended one sprite of its own since the transaction was recorded has shifted
+ * every index without touching anything the editor authored, and hashing those
+ * indexes would make every undo fail preflight as a content-conflict — the
+ * failure the three lane paid for as #81.
+ */
+
+import type { Container } from 'pixi.js';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { type JournalSubject, JsonHistoryResource } from '../history/json-history-resource';
+
+/** The stage root's stand-in uid: it is not one of the adapter's nodes, but it
+ *  is a legal parent for every op. */
+const ROOT_UID = '#root';
+
+/** The uid stamp, on the display object itself — the same technique
+ *  `AuthoringAdapter2D` uses for `__authId`, for the same reason (there is no
+ *  side table that survives the object outliving one walk). */
+interface StructureStamped {
+  __vgaiStructUid?: string;
+}
+
+/** A node's own local pose, as plain numbers. Recorded because `reparent`
+ *  rewrites it to preserve the world transform — undoing the move without
+ *  undoing that rewrite would leave the node in the right parent at the wrong
+ *  place. */
+interface CanvasNodePose {
+  x: number;
+  y: number;
+  rotation: number;
+  scaleX: number;
+  scaleY: number;
+  pivotX: number;
+  pivotY: number;
+  skewX: number;
+  skewY: number;
+}
+
+interface CanvasPlacement {
+  /** The parent's uid, {@link ROOT_UID} for the stage root, or `null` when the
+   *  node is detached (removed, or not yet added). */
+  parent: string | null;
+  /** Index among that parent's children; `-1` while detached. */
+  index: number;
+  pose?: CanvasNodePose;
+}
+
+export interface CanvasStructureState {
+  placements: Record<string, CanvasPlacement>;
+}
+
+function poseOf(object: Container): CanvasNodePose | undefined {
+  // A tracked node is not guaranteed to be a real PixiJS display object (the
+  // same tolerance `getTransform` and the structure watcher already carry).
+  if (!object.position || !object.scale || !object.pivot || !object.skew) return undefined;
+  return {
+    x: object.position.x,
+    y: object.position.y,
+    rotation: object.rotation,
+    scaleX: object.scale.x,
+    scaleY: object.scale.y,
+    pivotX: object.pivot.x,
+    pivotY: object.pivot.y,
+    skewX: object.skew.x,
+    skewY: object.skew.y,
+  };
+}
+
+function applyPose(object: Container, pose: CanvasNodePose): void {
+  if (!object.position || !object.scale || !object.pivot || !object.skew) return;
+  object.position.set(pose.x, pose.y);
+  object.scale.set(pose.scaleX, pose.scaleY);
+  object.pivot.set(pose.pivotX, pose.pivotY);
+  object.skew.set(pose.skewX, pose.skewY);
+  object.rotation = pose.rotation;
+}
+
+export class CanvasStructureHistory {
+  private readonly byUid = new Map<string, Container>();
+  private readonly resource: JsonHistoryResource<CanvasStructureState> | null;
+
+  constructor(
+    private readonly root: Container,
+    store: EditorShellStore,
+    /** Whose journal this structure stack belongs to — the world's for a held
+     *  surface, the run's for play (`history/json-history-resource.ts`). */
+    journal: JournalSubject,
+    /** Re-index + notify after a restore put objects back. */
+    private readonly onRestored: () => void,
+  ) {
+    const history = store.projectHistory;
+    this.resource = history
+      ? new JsonHistoryResource<CanvasStructureState>({
+          history,
+          kind: 'session-state',
+          scope: 'session',
+          subject: { ...journal, id: `${journal.id}/world-2d-structure` },
+          displayName: 'World 2D structure',
+          capture: () => this.capture(),
+          conflictIdentity: (state) =>
+            Object.fromEntries(
+              Object.entries(state.placements).map(([uid, placement]) => [uid, placement.parent]),
+            ),
+          restore: async (state) => {
+            this.restore(state);
+          },
+        })
+      : null;
+  }
+
+  /** Register a display object so its placement is journaled and so a detached
+   *  one can be found again. Idempotent; returns the uid. */
+  track(object: Container): string {
+    return this.uidOf(object);
+  }
+
+  /**
+   * Run ONE structural mutation as ONE undo entry.
+   *
+   * Every participant must be {@link track}ed BEFORE the call — including a
+   * node that does not exist in the tree yet, whose "before" placement is
+   * therefore `detached`, which is exactly what makes undo-of-create remove it.
+   */
+  run<T>(label: string, mutate: () => T): T {
+    this.resource?.assertCanMutate();
+    const before = this.capture();
+    const result = mutate();
+    if (this.resource) {
+      // JOURNALED LOUDLY. A rejected `record(...)` means the op IS applied to
+      // the live tree and has NO history entry: the user sees the node they
+      // created/moved/deleted and Ctrl+Z does nothing, with nothing said. Same
+      // statement (and same wording) as the three lane's `recordHistory`
+      // (`three-authoring-adapter.ts`).
+      //
+      // WHY THE REPORT IS HERE AND NOT IN THE VERB'S ACK. Every structural verb
+      // funnels through this method, and two of them — `structure.create` and
+      // `structure.duplicate` — return a synchronous node id by contract, so no
+      // caller can await this write. One report at the funnel is the only place
+      // that covers all of them identically; the pipe's ack answers a different
+      // question (where the BYTES went — nowhere, for this lane) and cannot
+      // carry a journaling failure without claiming it was a persistence one.
+      void this.resource.record(label, before, this.capture()).catch((error: unknown) => {
+        editorConsole.error(
+          `[canvas] failed to journal "${label}" into project history — the structural edit is ` +
+            `applied but has no history entry (it cannot be undone): ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          'authoring',
+        );
+      });
+    }
+    return result;
+  }
+
+  dispose(): void {
+    this.resource?.dispose();
+    this.byUid.clear();
+  }
+
+  private uidOf(object: Container): string {
+    if (object === this.root) return ROOT_UID;
+    const stamped = object as Container & StructureStamped;
+    const existing = stamped.__vgaiStructUid;
+    if (existing && this.byUid.get(existing) === object) return existing;
+    const uid = existing ?? `s${crypto.randomUUID()}`;
+    stamped.__vgaiStructUid = uid;
+    this.byUid.set(uid, object);
+    return uid;
+  }
+
+  private capture(): CanvasStructureState {
+    const placements: Record<string, CanvasPlacement> = {};
+    // `uidOf` may register an ancestor mid-iteration; a Map iterator visits
+    // entries added during the walk, so those ancestors get placements of their
+    // own — bounded by the depth of the tree, and what makes a restore able to
+    // name the parent it is putting a node back under.
+    for (const [uid, object] of this.byUid) {
+      const parent = (object.parent as Container | null) ?? null;
+      const pose = poseOf(object);
+      placements[uid] = {
+        parent: parent ? this.uidOf(parent) : null,
+        index: parent ? (parent.children?.indexOf(object) ?? -1) : -1,
+        ...(pose ? { pose } : {}),
+      };
+    }
+    return { placements };
+  }
+
+  private restore(state: CanvasStructureState): void {
+    const entries = Object.entries(state.placements);
+    // Detach first, so the indexes the attach pass reads are the ones the
+    // snapshot was taken against.
+    for (const [uid, placement] of entries) {
+      if (placement.parent !== null) continue;
+      const object = this.byUid.get(uid);
+      object?.parent?.removeChild(object);
+    }
+    for (const [uid, placement] of entries
+      .filter(([, placement]) => placement.parent !== null)
+      .sort((a, b) => a[1].index - b[1].index)) {
+      const object = this.byUid.get(uid);
+      if (!object) continue;
+      const parent =
+        placement.parent === ROOT_UID ? this.root : this.byUid.get(placement.parent as string);
+      if (!parent || typeof parent.addChildAt !== 'function') continue;
+      const capacity = parent.children.length - (object.parent === parent ? 1 : 0);
+      parent.addChildAt(object, Math.max(0, Math.min(placement.index, capacity)));
+      if (placement.pose) applyPose(object, placement.pose);
+    }
+    this.onRestored();
+  }
+}

package/src/host/authoring/pixi-transform-channels.ts

@@ -0,0 +1,205 @@
+/**
+ * The CANVAS surface's transform vocabulary, as pure functions.
+ *
+ * Pixi's transform is `x`, `y`, `rotation` (a scalar, radians, about the
+ * screen normal) and `scale` — there is no z and no quaternion. The editor's
+ * neutral {@link Transform} is 3D by construction, so the canvas adapter has to
+ * translate in both directions. It used to carry that `angleToQuat`/
+ * `quatToAngle` pair inline (extraction cited: `pixi-live-write-target.ts`'s
+ * own header records where the code it was lifted out of lived). This module
+ * is that pair plus the SOURCE half the write path needs, in one place, so the
+ * live and source targets can never disagree about what "rotation" means.
+ *
+ * ## Why the source half is pure, and lives here
+ *
+ * Deciding which `@pixi/react` PROP a transform channel writes is the whole
+ * literal-vs-dynamic contract of the canvas lane, and it is decidable from two
+ * inputs alone: the channel, and the JSX attributes already on the tag. No
+ * live tree, no network, no adapter. Keeping it here is what makes it testable
+ * without mounting Pixi (`packages/editor/test/pixi-transform-channels.test.ts`).
+ *
+ * ## The scale rule, stated once
+ *
+ * `<pixiContainer scale={0.5}>` is the shipped idiom (see any prefab under an
+ * example project's `prefabs/`), and Pixi's own setter takes a number or a
+ * `PointData` — never an array. So a UNIFORM scale writes the scalar back, and
+ * a NON-UNIFORM one is only expressible through `@pixi/react`'s dashed-prop
+ * piercing (`scale-x`/`scale-y`, which land on `container.scale.x`/`.y`). This
+ * module writes the dashed pair when the tag already authors it, and otherwise
+ * REFUSES a non-uniform scale in a sentence naming the pair — never a silently
+ * lossy uniform write, and never an array literal Pixi would reject at
+ * runtime.
+ */
+
+import type { Transform2DValue } from '@volter/game-runtime/pixi/authoring';
+import type { Transform } from '@volter/editor-project/adapter';
+
+/** Quaternion (xyzw) about Z ⇄ scalar radians — the one mapping both canvas
+ *  adapters use. */
+export function angleToQuat(a: number): [number, number, number, number] {
+  return [0, 0, Math.sin(a / 2), Math.cos(a / 2)];
+}
+
+export function quatToAngle(q: readonly [number, number, number, number]): number {
+  return 2 * Math.atan2(q[2], q[3]);
+}
+
+/** Pixi's own 2D transform → the editor's neutral 3D one (z pinned). */
+export function toNeutralTransform(t: Transform2DValue): Transform {
+  return {
+    position: [t.position[0], t.position[1], 0],
+    rotation: angleToQuat(t.rotation),
+    scale: [t.scale[0], t.scale[1], 1],
+  };
+}
+
+/** …and back. The z channel is DROPPED rather than folded in anywhere: a
+ *  canvas world has no depth axis, so carrying one would fabricate a value. */
+export function fromNeutralTransform(t: Transform): Transform2DValue {
+  return {
+    position: [t.position[0], t.position[1]],
+    rotation: quatToAngle(t.rotation),
+    scale: [t.scale[0], t.scale[1]],
+  };
+}
+
+/** The subset of `JsxAttrInfo` this planner reads — declared structurally so a
+ *  test can hand it plain objects. */
+export interface PixiAttr {
+  readonly name: string;
+  readonly rawValue: string;
+  readonly isExpression: boolean;
+  readonly isLiteral: boolean;
+}
+
+/** One `prop={value}` write the plan resolves to. `value` is SOURCE TEXT. */
+export interface PixiPropWrite {
+  readonly prop: string;
+  readonly value: string;
+}
+
+export type PixiChannelPlan =
+  | { readonly writable: true; readonly writes: readonly PixiPropWrite[] }
+  | { readonly writable: false; readonly reason: string };
+
+const NUMBER_RE = /^-?\d+(\.\d+)?$/;
+const EPS = 1e-6;
+
+/** ≤4 decimals, no trailing zeros, no negative zero — the same source-number
+ *  formatting the R3F writer uses. */
+export function formatSourceNumber(n: number): string {
+  const rounded = Math.round(n * 1e4) / 1e4;
+  return Object.is(rounded, -0) ? '0' : String(rounded);
+}
+
+function attr(attrs: readonly PixiAttr[], name: string): PixiAttr | undefined {
+  return attrs.find((candidate) => candidate.name === name);
+}
+
+/**
+ * A prop is writable when it is ABSENT (the writer appends it) or authored as
+ * a literal. An expression-bound prop (`x={grunt.x}`) is the sacred refusal:
+ * the game computes it every frame, so writing a number there would be a
+ * two-truths divergence the next tick erases.
+ */
+function propRefusal(attrs: readonly PixiAttr[], prop: string): string | null {
+  const found = attr(attrs, prop);
+  if (!found) return null;
+  if (found.isExpression && !found.isLiteral) {
+    return `${prop} is controlled by the JSX expression {${found.rawValue}}.`;
+  }
+  return null;
+}
+
+/**
+ * Which props one transform channel writes, given what the tag already says.
+ *
+ * `next` is the DESIRED transform in Pixi's own vocabulary. Returns the exact
+ * `prop={value}` writes to make, or one sentence saying why the channel is not
+ * writable here.
+ */
+export function planChannelWrite(
+  channel: 'position' | 'rotation' | 'scale',
+  next: Transform2DValue,
+  attrs: readonly PixiAttr[],
+): PixiChannelPlan {
+  if (channel === 'position') {
+    for (const prop of ['x', 'y'] as const) {
+      const refusal = propRefusal(attrs, prop);
+      if (refusal) return { writable: false, reason: refusal };
+    }
+    return {
+      writable: true,
+      writes: [
+        { prop: 'x', value: formatSourceNumber(next.position[0]) },
+        { prop: 'y', value: formatSourceNumber(next.position[1]) },
+      ],
+    };
+  }
+
+  if (channel === 'rotation') {
+    const refusal = propRefusal(attrs, 'rotation');
+    if (refusal) return { writable: false, reason: refusal };
+    return {
+      writable: true,
+      writes: [{ prop: 'rotation', value: formatSourceNumber(next.rotation) }],
+    };
+  }
+
+  // --- scale (see this module's header for the rule) ---
+  const dashed = attr(attrs, 'scale-x') ?? attr(attrs, 'scale-y');
+  if (dashed) {
+    for (const prop of ['scale-x', 'scale-y'] as const) {
+      const refusal = propRefusal(attrs, prop);
+      if (refusal) return { writable: false, reason: refusal };
+    }
+    return {
+      writable: true,
+      writes: [
+        { prop: 'scale-x', value: formatSourceNumber(next.scale[0]) },
+        { prop: 'scale-y', value: formatSourceNumber(next.scale[1]) },
+      ],
+    };
+  }
+
+  const refusal = propRefusal(attrs, 'scale');
+  if (refusal) return { writable: false, reason: refusal };
+  const authored = attr(attrs, 'scale');
+  if (authored && !NUMBER_RE.test(authored.rawValue.trim())) {
+    return {
+      writable: false,
+      reason:
+        `scale is authored as {${authored.rawValue}} — this editor writes the scalar ` +
+        'shorthand or the `scale-x`/`scale-y` pair, not an object literal.',
+    };
+  }
+  const [sx, sy] = next.scale;
+  if (Math.abs(sx - sy) >= EPS) {
+    return {
+      writable: false,
+      reason:
+        'A non-uniform scale needs the `scale-x`/`scale-y` props — this tag authors the ' +
+        'uniform `scale` shorthand, which cannot hold two values.',
+    };
+  }
+  return { writable: true, writes: [{ prop: 'scale', value: formatSourceNumber(sx) }] };
+}
+
+/** Whether two 2D transforms differ enough to be worth a source write. */
+export function transform2DChanged(
+  channel: 'position' | 'rotation' | 'scale',
+  before: Transform2DValue,
+  after: Transform2DValue,
+): boolean {
+  if (channel === 'position') {
+    return (
+      Math.abs(before.position[0] - after.position[0]) >= EPS ||
+      Math.abs(before.position[1] - after.position[1]) >= EPS
+    );
+  }
+  if (channel === 'rotation') return Math.abs(before.rotation - after.rotation) >= EPS;
+  return (
+    Math.abs(before.scale[0] - after.scale[0]) >= EPS ||
+    Math.abs(before.scale[1] - after.scale[1]) >= EPS
+  );
+}

package/src/host/authoring/selection-remount-handoff.ts

@@ -0,0 +1,23 @@
+/**
+ * One-shot selection handoff for UI remounts that rebuild the scene between
+ * the outgoing and incoming owners. Keys are weak so closing a store cannot
+ * leave editor state retained by the handoff.
+ */
+export class SelectionRemountHandoff<Key extends object> {
+  private readonly pending = new WeakMap<Key, readonly string[]>();
+
+  remember(key: Key, selection: Iterable<string>): void {
+    const ids = [...selection];
+    if (ids.length === 0) this.pending.delete(key);
+    else this.pending.set(key, ids);
+  }
+
+  take(key: Key, currentSelection: Iterable<string>): readonly string[] {
+    const current = [...currentSelection];
+    const previous = this.pending.get(key) ?? [];
+    this.pending.delete(key);
+    // A selection made while the incoming owner was mounting is newer than
+    // the outgoing owner's handoff and must win.
+    return current.length > 0 ? current : previous;
+  }
+}