@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/authoring/story-overlay.ts

@@ -22,7 +22,7 @@
  * `world-session-state.ts`'s own stance — nothing here needs a
  * project-switch reset within a single browser tab.
  */
-import type { UIStory } from '@vgai/scene-ui/registry';
+import type { UIStory } from './story-types';
 
 const _overlays = new Map<string, Record<string, UIStory>>();
 

package/src/authoring/story-types.ts

@@ -0,0 +1,11 @@
+import type { ComponentType } from 'react';
+
+/** Portable design-time state used by React-root authoring. */
+export interface UIStory {
+  label: string;
+  data: Record<string, unknown>;
+  props?: Record<string, unknown>;
+}
+
+/** Optional React component catalog used by the root authoring adapter. */
+export type UIComponentRegistry = Record<string, ComponentType<Record<string, unknown>>>;

package/src/authoring/vgai-scene-authoring-adapter.ts

@@ -15,6 +15,7 @@ import type {
   AssetDropProvider,
   AuthoringAdapter,
   AuthoringCapabilities,
+  AuthoringProvenance,
   ComponentsProvider,
   EditorNode,
   FileMapProvider,
@@ -56,7 +57,8 @@ function fieldKindToPropertyType(kind: FieldKind): PropertyDescriptor['type'] {
 }
 
 // ---------------------------------------------------------------------------
-// D8 — root groups (radio roots over the project's `*.vscn.json` files)
+// D8 compatibility activation index over project `*.vscn.json` files.
+// Only the active document is projected into the hierarchy (D19/D20).
 // ---------------------------------------------------------------------------
 
 const SCENE_ROOT_PREFIX = 'sceneRoot:';
@@ -77,7 +79,9 @@ function normalizeScenePath(path: string): string {
   return path.startsWith('/') ? path.slice(1) : path;
 }
 
-async function fetchSceneDoc(path: string): Promise<SceneFile> {
+/** Exported for `edit-mode-authoring.ts`'s `switchFocusedWorld` (A4) — the
+ *  one scene-fetch path both root activation and world focus-switch share. */
+export async function fetchSceneDoc(path: string): Promise<SceneFile> {
   // Mirrors `initial-scene.ts`'s browser-vs-server branch: browser builds
   // read scene files through the active `StorageBackend` (OPFS/File System
   // Access), not `fetch()`; the server dev build serves them over HTTP.
@@ -101,6 +105,7 @@ function toNode(e: SceneEntity, parentId: string | null): EditorNode {
   return {
     id: e.id!,
     label: e.name,
+    role: 'entity',
     kind: kindOf(e),
     parentId,
     childIds: (e.children ?? []).map((c) => c.id!),
@@ -322,23 +327,35 @@ export class VgaiSceneAuthoringAdapter implements AuthoringAdapter {
     persist: true,
   };
 
+  readonly provenance: AuthoringProvenance = {
+    source: 'document',
+    label: 'scene',
+    detail: 'Authored scene document — edits save to the .vscn scene file.',
+  };
+
   subscribe(listener: () => void): () => void {
     return this.store.subscribe(listener);
   }
 
   readonly hierarchy: HierarchyProvider = {
-    // D8 — member (scene-file root) rows are APPENDED after the store's own
-    // entity roots (never interleaved between them): several existing e2e
-    // specs range-select or index-scan entity rows by relative position
-    // (`29-game-hierarchy.spec.ts`'s multi-select, drag-reorder) — appending
-    // keeps every entity's relative order/adjacency byte-identical to today,
-    // the only delta is N additional childless rows at the tail.
-    roots: () => [...this.store.entities.map((e) => toNode(e, null)), ...this.memberNodes()],
+    // D19/D20 — hierarchy is the active world content, not a project-wide
+    // checklist. The active scene is a real document row; other scene files
+    // remain assets until opened. A transient/untitled store (unit fixtures,
+    // browser import before first save) honestly has no document and retains
+    // the flat entity-root shape.
+    roots: () => {
+      const path = this.activeScenePath();
+      return path ? [this.memberNode(path)!] : this.store.entities.map((e) => toNode(e, null));
+    },
     node: (id) => {
       const memberPath = pathForSceneRootId(id);
       if (memberPath !== null) return this.memberNode(memberPath);
       const hit = findInTree(this.store.entities, id);
-      return hit ? toNode(hit.entity, hit.parentId) : null;
+      if (!hit) return null;
+      return toNode(
+        hit.entity,
+        hit.parentId ?? (this.activeScenePath() ? sceneRootId(this.activeScenePath()!) : null),
+      );
     },
     object3D: (id) => this.store.objectMap.get(id) ?? null,
     idForObject3D: (o) => (getUserData(o, 'entityId') as string | undefined) ?? null,
@@ -351,36 +368,48 @@ export class VgaiSceneAuthoringAdapter implements AuthoringAdapter {
     return getCachedProjectScenes();
   }
 
-  private memberNodes(): EditorNode[] {
-    return this.scenesList()
-      .map((path) => this.memberNode(path))
-      .filter((n): n is EditorNode => n !== null);
+  private activeScenePath(): string | null {
+    return this.store.savePath ? normalizeScenePath(this.store.savePath) : null;
+  }
+
+  private sceneLabel(path: string): string {
+    const file = path.split('/').pop() ?? path;
+    const stem = file.replace(/\.vscn\.json$/i, '').replace(/\.json$/i, '');
+    const words = stem
+      .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+      .replace(/[-_]+/g, ' ')
+      .trim();
+    return words ? words.replace(/\b\w/g, (letter) => letter.toUpperCase()) : file;
   }
 
   /** `null` for a path that isn't (or is no longer) a known project scene —
    *  a stale/dangling `sceneRoot:` id resolves to nothing rather than a
    *  fabricated node. */
   private memberNode(path: string): EditorNode | null {
-    if (!this.scenesList().includes(path)) return null;
+    const activePath = this.activeScenePath();
+    if (!this.scenesList().includes(path) && activePath !== path) return null;
     const isActive =
       this.store.savePath !== null && normalizeScenePath(this.store.savePath) === path;
     return {
       id: sceneRootId(path),
-      label: path,
-      kind: 'object',
+      label: this.sceneLabel(path),
+      secondaryLabel: path,
+      role: 'document',
+      kind: 'scene',
       parentId: null,
-      childIds: [],
-      // D8 — member of a RootGroup, not the active one (see `authoring.ts`'s
-      // `EditorNode.flags.inactiveRoot` doc). The active member gets NO flag
-      // so both radio states are plain childless rows (GameHierarchy renders
-      // the ● / ○ radio from `rootGroups` data, not from this flag alone).
+      childIds: isActive ? this.store.entities.map((entity) => entity.id!) : [],
+      // D8 — member of the compatibility activation index, not its active
+      // document (see `authoring.ts`'s `inactiveRoot` contract). Inactive
+      // members are resolvable for file opening but are not hierarchy roots.
       flags: isActive ? {} : { inactiveRoot: true },
     };
   }
 
   /**
-   * D8 — one mutually-exclusive "Scenes" group over every project
-   * `*.vscn.json`. `activate()` flushes a pending autosave first (belt: the
+   * Activation index over project `*.vscn.json` assets. Only its active member
+   * is projected as the hierarchy's document row; inactive members stay in
+   * this file-opening index instead of becoming a scene checklist. `activate()`
+   * flushes a pending autosave first (belt: the
    * 300ms debounce could otherwise lose an edit made just before switching),
    * then loads the target scene into the live store exactly like opening it
    * from the asset browser (`DefaultEditorLayout.tsx`'s `openSceneFromAsset`
@@ -676,7 +705,7 @@ export class VgaiSceneAuthoringAdapter implements AuthoringAdapter {
       this.store.moveEntity([id], parentId, index);
     },
     // A2 parity growth — the former toolbar-only `addMenuItems` list (12
-    // kinds), now driving the shell's generic Create▸ palette for ANY
+    // kinds), now driving the shell's generic Create submenu for ANY
     // parent (root via the toolbar `+`, or a specific row via the context
     // menu) — a capability the old toolbar-only Add menu never had.
     creatableKinds: () =>

package/src/authoring/viewport-tool-context.ts

@@ -0,0 +1,78 @@
+import type { AuthoringAdapter } from '@engine/adapter';
+import type { EditorStore } from '../editor-store';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { resolveFocusedViewportWorldId } from './world-hidden-viewport';
+import { isWorldHidden } from './world-session-state';
+
+/**
+ * The one native root whose viewport tools may claim the current selection.
+ *
+ * Viewport content can contain several roots at once, but editing chrome needs
+ * one unambiguous coordinate system and capability owner. Empty,
+ * organizational, and cross-root selections therefore resolve to `null`.
+ */
+export interface ViewportToolContext {
+  readonly worldId: string | null;
+  readonly kind: string;
+  readonly adapter: AuthoringAdapter;
+}
+
+function compositeContext(
+  composite: CompositeAuthoringAdapter,
+  selectedIds: readonly string[],
+): ViewportToolContext | null {
+  const children = composite.childAdapters();
+  let owner: (typeof children)[number] | null = null;
+
+  for (const id of selectedIds) {
+    const child =
+      children.find((candidate) => composite.groupNodeId(candidate.worldId) === id) ??
+      children.find((candidate) => composite.ownerOf(id) === candidate.worldId);
+    // Kind/projection folders and stale ids do not claim native-world tools.
+    if (!child) return null;
+    // A heterogeneous selection has no single native editing context.
+    if (owner && owner.worldId !== child.worldId) return null;
+    owner = child;
+  }
+
+  return owner ? { worldId: owner.worldId, kind: owner.kind, adapter: owner.adapter } : null;
+}
+
+/**
+ * Resolve viewport-tool ownership from selection, never from which roots
+ * merely exist or happen to be visible.
+ */
+export function resolveViewportToolContext(
+  adapter: AuthoringAdapter,
+  selectedIds: Iterable<string>,
+): ViewportToolContext | null {
+  const ids = [...selectedIds];
+  if (ids.length === 0) return null;
+  if (adapter instanceof CompositeAuthoringAdapter) return compositeContext(adapter, ids);
+
+  // Legacy/single-adapter sessions have no manifest kind metadata. Keep the
+  // fallback structural and conservative: a rect-capable selection is DOM;
+  // a selection whose every node resolves to Object3D is Three.js. Unknown
+  // adapters advertise no kind-specific chrome rather than guessing.
+  if (ids.some((id) => adapter.hierarchy.node(id) === null)) return null;
+  if (adapter.rects) return { worldId: null, kind: 'react', adapter };
+  if (ids.every((id) => adapter.hierarchy.object3D(id) !== null)) {
+    return { worldId: null, kind: 'threejs', adapter };
+  }
+  return null;
+}
+
+/**
+ * Whether the selected owner is actually painted in this viewport. DOM
+ * layers follow their world eye; among several Three.js roots only the one
+ * focused into the editor's single live Three.js scene can own its cockpit.
+ */
+export function isViewportToolContextVisible(
+  store: EditorStore,
+  context: ViewportToolContext | null,
+): boolean {
+  if (!context) return false;
+  if (context.worldId !== null && isWorldHidden(context.worldId)) return false;
+  if (context.kind !== 'threejs' || context.worldId === null) return true;
+  return resolveFocusedViewportWorldId(store) === context.worldId;
+}

package/src/authoring/world-canvas-viewport-state.ts

@@ -0,0 +1,35 @@
+/** Session-only responsive canvas size for DOM-backed authoring roots. */
+export interface WorldCanvasViewport {
+  readonly width: number | null;
+  readonly height: number | null;
+}
+
+const FILL_VIEWPORT: WorldCanvasViewport = { width: null, height: null };
+let viewport: WorldCanvasViewport = FILL_VIEWPORT;
+const listeners = new Set<() => void>();
+
+export function getWorldCanvasViewport(): WorldCanvasViewport {
+  return viewport;
+}
+
+export function setWorldCanvasViewport(width: number | null, height: number | null): void {
+  const nextWidth = width === null ? null : Math.max(1, Math.round(width));
+  const nextHeight = height === null ? null : Math.max(1, Math.round(height));
+  if (viewport.width === nextWidth && viewport.height === nextHeight) return;
+  viewport = { width: nextWidth, height: nextHeight };
+  for (const listener of listeners) listener();
+}
+
+export function resetWorldCanvasViewport(): void {
+  setWorldCanvasViewport(null, null);
+}
+
+export function subscribeWorldCanvasViewport(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function _resetWorldCanvasViewportForTest(): void {
+  viewport = FILL_VIEWPORT;
+  listeners.clear();
+}

package/src/authoring/world-hidden-viewport.ts

@@ -0,0 +1,186 @@
+/**
+ * World-hidden eye (D9, `world-session-state.ts`) applied to the EDIT-mode
+ * threejs viewport.
+ *
+ * Bug this fixes: the eye on a hierarchy world-group row (`world:<id>
+ * (<kind>)`, shown for 2+ world manifests) toggles `isWorldHidden(worldId)`
+ * and culls the hierarchy subtree, but for a react/pixi world that's ALSO the
+ * only thing that mattered — `design-time-layers.ts`'s `applySessionStyle`
+ * sets `display:none` on that world's DOM layer. A threejs world has no DOM
+ * layer; nothing consumed `isWorldHidden` for its actual `THREE.Object3D`s
+ * before this module existed, so the eye was a no-op in the viewport.
+ *
+ * Session-local only (never touches entity descriptors/undo/the `.vscn`
+ * file, matching the DOM roots' own `display:none` semantics): every call
+ * RECOMPUTES `obj.visible` from two already-authoritative, already-live
+ * sources —
+ *   - the entity's OWN visible flag, read back off `userData['entity']`
+ *     (the descriptor `scene-sync.ts` stamps onto every object it builds —
+ *     see ARCHITECTURE.md's "the world node IS the entity"), which is the
+ *     SAME flag the generic inspector's eye writes via
+ *     `VgaiSceneAuthoringAdapter.inspector.set(id, 'visible', …)`;
+ *   - `!isWorldHidden(focusedWorldId)`.
+ * ANDing per call (never "remembering" a previous visibility) is what makes
+ * this rebuild-proof: a full or single-entity `scene-sync.ts` rebuild
+ * re-stamps `obj.visible = entity.visible !== false` from the descriptor,
+ * silently dropping any one-shot override — but the very next call here puts
+ * the world-hidden override back, and it never clobbers a per-entity
+ * `visible:false` because that flag is read fresh from the descriptor each
+ * time rather than assumed. Callers must re-invoke this after every rebuild
+ * AND after the toggle itself; `editor-viewport.ts`'s `syncFromStore()` is
+ * exactly that seam — it already re-runs on every `store.subscribe` notify,
+ * which covers both a scene-sync rebuild (which notifies) and
+ * `GameHierarchy.tsx`'s toggle handler (`toggleWorldHidden` +
+ * `store.notifyIngestEdit()`).
+ *
+ * Multi-threejs-world limitation (by design, not an oversight): a composite's
+ * `store.objectMap`/live THREE.Scene only ever holds ONE threejs world's real
+ * objects — the "focused" one resolved by
+ * `edit-mode-authoring.ts`'s `resolveFocusedThreejsWorldId` at composite
+ * install time (whichever world's scene `loadInitialScene` loaded into the
+ * store). Every OTHER threejs-kind world in the manifest gets a read-only
+ * `BoundaryAuthoringAdapter` with NO live geometry in this viewport at all.
+ * A4's `switchFocusedWorld` (landed — `edit-mode-authoring.ts`) changes WHICH
+ * world is the focused one (document + `?scene=` + rebuild together), but at
+ * any instant there is still exactly ONE: `resolveFocusedViewportWorldId`
+ * below only ever needs to name ONE worldId, not walk per-object ownership —
+ * true CONCURRENT multi-threejs-world rendering remains out of scope.
+ */
+
+import { getUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import type { EditorStore } from '../editor-store';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { isWorldHidden } from './world-session-state';
+
+/**
+ * The worldId of the ONE threejs world actually rendered in this viewport
+ * (`store.objectMap`'s contents), or `null` when the active adapter isn't a
+ * composite (single-world project — no world-group row/eye exists for it at
+ * all, so there is nothing to resolve) or declares no threejs world.
+ *
+ * Distinguishes the focused, LIVE `VgaiSceneAuthoringAdapter` from every
+ * other (possibly also `kind: 'threejs'`) child's read-only
+ * `BoundaryAuthoringAdapter` by `capabilities.transform` — the Boundary
+ * adapter's capabilities are all `false` (see `boundary-authoring-adapter.ts`),
+ * while `VgaiSceneAuthoringAdapter` is the only child that ever reports
+ * `transform: true`. This reuses an existing, already-load-bearing signal
+ * instead of adding a new `instanceof` check or a parallel "which world is
+ * focused" bookkeeping slot.
+ */
+export function resolveFocusedViewportWorldId(store: EditorStore): string | null {
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) return null;
+  const focused = active
+    .childAdapters()
+    .find((c) => c.kind === 'threejs' && c.adapter.capabilities.transform);
+  return focused?.worldId ?? null;
+}
+
+/**
+ * Apply the eye toggle to every object in `objectMap` (see module doc
+ * comment for the full rebuild-proofing rationale). `focusedWorldId` is
+ * accepted as a parameter (rather than re-resolved internally) so a caller
+ * that already computed it once per call (e.g. for a cheap re-apply
+ * signature) doesn't pay for `resolveFocusedViewportWorldId`'s composite walk
+ * twice.
+ */
+export function applyWorldHiddenVisibility(
+  objectMap: ReadonlyMap<string, THREE.Object3D>,
+  focusedWorldId: string | null,
+): void {
+  const hidden = focusedWorldId !== null && isWorldHidden(focusedWorldId);
+  for (const obj of objectMap.values()) {
+    // Structural read of the ONE descriptor field this module consumes —
+    // deliberately not the SceneEntity type (the authoring-inversion ratchet:
+    // only the first-party adapter allowlist may import it).
+    const entity = getUserData(obj, 'entity') as { visible?: boolean } | undefined;
+    // Defensive fallback for the (should-never-happen) case of an objectMap
+    // entry with no stamped descriptor: leave its current visibility alone
+    // rather than guessing, UNLESS the world itself is hidden (the eye still
+    // wins — nothing in a hidden world should render).
+    const ownVisible = entity ? entity.visible !== false : obj.visible;
+    obj.visible = hidden ? false : ownVisible;
+  }
+}
+
+/**
+ * Matches `scene-sync.ts`'s `applyEnvironment` DEFAULT_BG — what an editor
+ * viewport with NO authored environment shows. A single shared instance so
+ * the per-notify re-apply below never allocates.
+ */
+const HIDDEN_WORLD_BACKGROUND = new THREE.Color('#aaaaaa');
+
+/**
+ * The scene-level half of the eye: `applyWorldHiddenVisibility` above only
+ * covers entity `Object3D`s (the `objectMap`), but a threejs world also
+ * renders things that live directly on the `THREE.Scene` — the authored
+ * `background` color/skybox, `fog`, IBL `environment`, and the
+ * `envObject`-tagged ambient light `applyEnvironment` adds. None of those are
+ * entities, so before this function existed, hiding the world left the
+ * viewport painted in the world's background color (looking exactly like
+ * "the eye didn't work").
+ *
+ * Same recompute-don't-remember contract as above: this only ever writes the
+ * SUPPRESSED state, idempotently, and callers invoke it on every notify while
+ * the world is hidden (an inspector environment edit mid-hide re-paints the
+ * authored values via `_applyEnvironment` — the very next notify re-suppresses
+ * them here). The restore path is `EditorStore.reapplyEnvironment()`, whose
+ * truth is `_sceneMeta.environment` — never a snapshot taken here.
+ *
+ * Post-processing (bloom/vignette) is the composer's half: `ViewportPanel`'s
+ * `rebuildComposer` passes `undefined` instead of `store.environment` while
+ * the world is hidden; `editor-viewport.ts` bumps `composerVersion` (via
+ * `reapplyEnvironment`) on both hide/show edges so that rebuild actually runs.
+ */
+export function suppressWorldEnvironment(scene: THREE.Scene): void {
+  scene.background = HIDDEN_WORLD_BACKGROUND;
+  scene.fog = null;
+  scene.environment = null;
+  scene.traverse((obj) => {
+    if (getUserData(obj, 'envObject')) obj.visible = false;
+  });
+}
+
+/**
+ * Is a threejs surface currently SHOWING in the viewport? This is the single
+ * derived truth the 3D cockpit chrome gates on (spec 28,
+ * `docs/unified-world-editor/28-conditional-viewport-chrome.md`): the grid,
+ * orientation gizmo, transform toolstrip, camera readout, shading modes, and
+ * the transform gizmo itself are claims about what the user can do RIGHT NOW
+ * — showing them over a viewport with no visible 3D content is a false claim
+ * (same spirit as the adapter tier rule: degrade loudly, never advertise
+ * what isn't there). The DOM half of the chrome (`WorldSelectionOverlay`)
+ * already self-gates this way; this selector brings the pre-contract 3D
+ * chrome under the same rule.
+ *
+ * Truth table (deliberately conservative — every non-composite mode keeps
+ * today's behavior exactly):
+ *  - active adapter is not a composite (single-world project, classic scene
+ *    editing, ingest): `true` — no world-group eyes exist there, nothing to
+ *    derive from, status quo.
+ *  - composite with NO threejs-kind child at all (e.g. react-only
+ *    multi-world manifest): `false` — no 3D content can EVER show.
+ *  - composite whose only threejs children are unfocused read-only
+ *    Boundaries (`resolveFocusedViewportWorldId` → null): `true` — such a
+ *    world has no live geometry here (even with A4's `switchFocusedWorld`
+ *    landed, exactly one threejs world is live at a time and this state is
+ *    reachable transiently around a rebuild), but it is manifest-declared 3D
+ *    content; keep the cockpit rather than flickering chrome on
+ *    adapter-install timing.
+ *  - composite with a focused live threejs world: `!isWorldHidden(worldId)`
+ *    — the eye is the "what we're showing" signal.
+ *
+ * Recompute-per-call like everything else in this module: callers read it on
+ * every store notify (`syncFromStore` / `ViewportPanel` render), never cache
+ * it across notifies.
+ */
+export function isThreejsSurfaceVisible(store: EditorStore): boolean {
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) return true;
+  const children = active.childAdapters();
+  if (!children.some((c) => c.kind === 'threejs')) return false;
+  const focusedId = resolveFocusedViewportWorldId(store);
+  return focusedId === null ? true : !isWorldHidden(focusedId);
+}

package/src/authoring/world-pan-state.ts

@@ -1,8 +1,8 @@
 /**
- * World pan state (spec27 §8 "space-pan" row, D4 rebuild —
+ * Shared DOM-world canvas transform (spec27 §8 "space-pan" row, D4 rebuild —
  * docs/unified-world-editor/27-visual-react-editing.md) — a module-level
  * subscribable singleton (mirrors `eyedropper-session.ts`'s "bare singleton +
- * own listener set" shape) holding the CURRENT SHARED pan translate `(x, y)`
+ * own listener set" shape) holding the CURRENT SHARED pan + zoom
  * applied, in LOCKSTEP, to both every design-time world-layer host
  * (`design-time-layers.ts`'s `createLayerElement`-produced react/pixi layers)
  * and `WorldSelectionOverlay`'s own outer wrapper.
@@ -18,17 +18,19 @@
  * IDENTICAL `(x, y)` delta — a rigid subtree translation — so the
  * subtraction is invariant under pan: `rect(id)` returns the SAME
  * host-relative numbers at any pan offset, unmodified, with no pan-awareness
- * needed in the adapter, `inspect.ts`'s geometry math, or any of the ~14
- * overlay chrome consumers. `PickProvider.pick` needs no changes either — it
+ * needed in `inspect.ts`'s geometry math or the overlay chrome consumers.
+ * Zoom scales both measured rectangles; `toHostRelative` divides their
+ * offsets and dimensions by the shared zoom before exposing authored-space
+ * geometry, while `WorldSelectionOverlay.toHostLocal` performs the inverse
+ * for pointer gestures. `PickProvider.pick` needs no changes — it
  * hit-tests real rendered rects against the real client cursor position,
  * both of which already reflect the applied transform natively.
  *
  * Applying the exact SAME transform to `WorldSelectionOverlay`'s own outer
  * wrapper (a SIBLING of every world-layer host inside the SAME
  * `ViewportPanel` containerRef parent — see that file's own mount-site doc
- * comment) shifts the overlay's local coordinate origin by the identical
- * `(x, y)` — so drawing a chrome element at `rect(id)`'s (pan-invariant)
- * host-relative `(x, y)` inside the panned overlay wrapper lands it at the
+ * comment) shifts and scales the overlay by the identical transform — so
+ * drawing a chrome element at `rect(id)`'s authored coordinates lands it at the
  * SAME screen position as the panned live element it describes. This is the
  * entire "lockstep" contract: every consumer on both sides of the pan reads
  * ONE shared value (`getWorldPan()`) and applies it through the ONE shared
@@ -39,9 +41,10 @@
 export interface WorldPan {
   readonly x: number;
   readonly y: number;
+  readonly zoom: number;
 }
 
-const ZERO_PAN: WorldPan = { x: 0, y: 0 };
+const ZERO_PAN: WorldPan = { x: 0, y: 0, zoom: 1 };
 
 let _pan: WorldPan = ZERO_PAN;
 const listeners = new Set<() => void>();
@@ -50,16 +53,27 @@ function notify(): void {
   for (const l of listeners) l();
 }
 
-/** The current shared pan translate, in CSS px. */
+/** The current shared canvas transform; x/y are CSS px and zoom is unitless. */
 export function getWorldPan(): WorldPan {
   return _pan;
 }
 
+/** Set the complete shared canvas transform in one subscriber notification. */
+export function setWorldView(x: number, y: number, zoom: number): void {
+  const nextZoom = Math.min(4, Math.max(0.1, zoom));
+  if (_pan.x === x && _pan.y === y && _pan.zoom === nextZoom) return;
+  _pan = { x, y, zoom: nextZoom };
+  notify();
+}
+
 /** Set the shared pan translate to an absolute `(x, y)`. */
 export function setWorldPan(x: number, y: number): void {
-  if (_pan.x === x && _pan.y === y) return;
-  _pan = { x, y };
-  notify();
+  setWorldView(x, y, _pan.zoom);
+}
+
+/** Set the shared canvas zoom while preserving its current pan. */
+export function setWorldZoom(zoom: number): void {
+  setWorldView(_pan.x, _pan.y, zoom);
 }
 
 /** Set the shared pan translate by a RELATIVE `(dx, dy)` — a convenience
@@ -71,19 +85,19 @@ export function panWorldBy(dx: number, dy: number): void {
   setWorldPan(_pan.x + dx, _pan.y + dy);
 }
 
-/** Reset pan to `(0, 0)` — called on a world-layer remount (`design-time-
+/** Reset pan to `(0, 0)` and zoom to 100% — called on a world-layer remount (`design-time-
  *  layers.ts`'s `mountDesignTimeLayers`, invoked on initial edit-mode install
  *  AND every `'editor:edit-mode-rebuild'`), so switching/reloading the active
  *  world set never leaves a stale pan offset applied over a DIFFERENT layer
  *  stack. A no-op (no `notify()`) when already at rest, so a fresh session
  *  never fires a spurious subscriber tick. */
 export function resetWorldPan(): void {
-  if (_pan.x === 0 && _pan.y === 0) return;
+  if (_pan.x === 0 && _pan.y === 0 && _pan.zoom === 1) return;
   _pan = ZERO_PAN;
   notify();
 }
 
-/** Subscribe to pan changes — both `design-time-layers.ts` (imperative DOM
+/** Subscribe to canvas-transform changes — both `design-time-layers.ts` (imperative DOM
  *  style writes) and `WorldSelectionOverlay` (`useSyncExternalStore`) bind
  *  this so every lockstep mount point re-applies the SAME new value the
  *  instant it changes. */
@@ -102,8 +116,10 @@ export function subscribeWorldPan(listener: () => void): () => void {
  * to its pre-this-feature output.
  */
 export function panTransformValue(pan: WorldPan): string | undefined {
-  if (pan.x === 0 && pan.y === 0) return undefined;
-  return `translate(${pan.x}px, ${pan.y}px)`;
+  if (pan.x === 0 && pan.y === 0 && pan.zoom === 1) return undefined;
+  if (pan.zoom === 1) return `translate(${pan.x}px, ${pan.y}px)`;
+  if (pan.x === 0 && pan.y === 0) return `scale(${pan.zoom})`;
+  return `translate(${pan.x}px, ${pan.y}px) scale(${pan.zoom})`;
 }
 
 /** Test-only reset (mirrors `eyedropper-session.ts`'s/`world-session-

package/src/authoring/world-session-state.ts

@@ -21,7 +21,7 @@
  *    B1 only stores/exposes the toggle; nothing reads it yet.
  *
  * Keyed by the RAW manifest world id (`CompositeChild.worldId` /
- * `ResolvedWorldEntry.id`) — the SAME id `design-time-layers.ts` gets from
+ * `ResolvedAdapterRoot.id`) — the SAME id `design-time-layers.ts` gets from
  * `composite.childAdapters()`, NOT the composite's synthetic `world:<id>`
  * group-node id. `GameHierarchy.tsx` (whose rows ARE keyed by the group-node
  * id) resolves the raw worldId via `compositeGroupBadge`'s `worldId` field