@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/authoring/first-party-inspector/is-first-party-selection.ts

@@ -18,13 +18,14 @@ import { CompositeAuthoringAdapter } from '../composite-authoring-adapter';
 import { VgaiSceneAuthoringAdapter } from '../vgai-scene-authoring-adapter';
 
 /**
- * True when `node` (or, if `null`, the "no selection" case) is owned by a
- * first-party `VgaiSceneAuthoringAdapter` — INCLUDING the null-selection
- * fallback: a composite with no selected node falls back to "does a
- * first-party child exist at all" (in every production shape there is at
- * most one — the edit-mode composite's focused threejs world — so this is
- * equivalent to "the focused/first-party child exists" without needing a
- * separate "focused" concept).
+ * True when `node` is a real Object3D-backed entity owned by a first-party
+ * `VgaiSceneAuthoringAdapter`, or when `node` is null and the active adapter
+ * has a first-party scene child (the no-selection Environment state).
+ *
+ * A scene document row is intentionally false: it is owned by the scene
+ * adapter for hierarchy routing, but it is not a SceneEntity and therefore
+ * cannot be passed to entity-only sections such as HeaderSection. Document
+ * rows have their own Environment registration in `register.tsx`.
  */
 export function isFirstPartySelection(node: EditorNode | null, adapter: AuthoringAdapter): boolean {
   const id = node?.id ?? null;
@@ -35,10 +36,28 @@ export function isFirstPartySelection(node: EditorNode | null, adapter: Authorin
     const owner = adapter.ownerOf(id);
     if (owner === null) return false; // world:<id> group node or unrecognized id -> generic
     const child = adapter.childAdapters().find((c) => c.worldId === owner);
-    return child?.adapter instanceof VgaiSceneAuthoringAdapter;
+    return (
+      child?.adapter instanceof VgaiSceneAuthoringAdapter &&
+      child.adapter.hierarchy.object3D(id) !== null
+    );
+  }
+  if (!(adapter instanceof VgaiSceneAuthoringAdapter)) return false;
+  return id === null || adapter.hierarchy.object3D(id) !== null;
+}
+
+/** True only for a first-party scene's synthetic document/root row. */
+export function isFirstPartySceneDocument(
+  node: EditorNode | null,
+  adapter: AuthoringAdapter,
+): boolean {
+  if (!node || node.role !== 'document') return false;
+  if (adapter instanceof CompositeAuthoringAdapter) {
+    const owner = adapter.ownerOf(node.id);
+    if (owner === null) return false;
+    return (
+      adapter.childAdapters().find((child) => child.worldId === owner)?.adapter instanceof
+      VgaiSceneAuthoringAdapter
+    );
   }
-  // Bare (non-composite) adapter: first-party-ness doesn't depend on
-  // selection at all — a bare `VgaiSceneAuthoringAdapter` is first-party
-  // whether or not anything is selected; a bare ingest/module override never is.
   return adapter instanceof VgaiSceneAuthoringAdapter;
 }

package/src/authoring/first-party-inspector/register.tsx

@@ -44,9 +44,9 @@ import {
 import { AddSectionMenu } from './AddSectionMenu';
 import { EnvironmentSection } from './EnvironmentSection';
 import { HeaderSection } from './HeaderSection';
-import { isFirstPartySelection } from './is-first-party-selection';
+import { isFirstPartySceneDocument, isFirstPartySelection } from './is-first-party-selection';
 
-export { isFirstPartySelection };
+export { isFirstPartySceneDocument, isFirstPartySelection };
 
 /** A first-party selection (an actual node, not the deselect state). */
 const isSelected = (node: EditorNode | null, adapter: AuthoringAdapter): boolean =>
@@ -56,6 +56,10 @@ const isSelected = (node: EditorNode | null, adapter: AuthoringAdapter): boolean
 const isDeselected = (node: EditorNode | null, adapter: AuthoringAdapter): boolean =>
   node === null && isFirstPartySelection(node, adapter);
 
+/** A first-party scene document row shows scene settings, not entity fields. */
+const isSceneDocument = (node: EditorNode | null, adapter: AuthoringAdapter): boolean =>
+  isFirstPartySceneDocument(node, adapter);
+
 /**
  * Adapt a `SectionProps`-based typed section (the existing
  * `components/inspectors/*.tsx` components, which already read the live
@@ -95,6 +99,13 @@ registerInspectorSections({ match: isSelected, Section: wrap(NavigationSection)
 registerInspectorSections({ match: isSelected, Section: wrap(ComponentsSection) });
 registerInspectorSections({ match: isSelected, Section: wrap(AddSectionMenu) });
 
+registerInspectorSections({
+  match: isSceneDocument,
+  Section: EnvironmentSection,
+  suppresses: ['header', 'transform', 'properties', 'components', 'stories'],
+  panelName: 'Inspector',
+});
+
 registerInspectorSections({
   match: isDeselected,
   Section: EnvironmentSection,

package/src/authoring/ingest-authoring-adapter.ts

@@ -30,6 +30,7 @@
 import type {
   AuthoringAdapter,
   AuthoringCapabilities,
+  AuthoringProvenance,
   EditorNode,
   HierarchyProvider,
   InspectorProvider,
@@ -47,12 +48,31 @@ import {
   colorMaterialOf,
 } from '@engine/adapter/ingest/overlay-apply';
 import type * as THREE from 'three';
+import { editorConsole } from '../editor-console';
 import type { EditorStore } from '../editor-store';
+import { JsonHistoryResource } from '../history/json-history-resource';
 import { captureSubtreeToVscn } from './ingest-capture';
 import type { IngestOverlay } from './ingest-overlay';
-import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
 import { raycastPick } from './viewport-raycast';
 
+interface IngestHistoryState {
+  overlay: IngestOverlay;
+  objects: Record<
+    string,
+    {
+      name: string;
+      visible: boolean;
+      transform: Transform;
+      color?: string;
+      lightIntensity?: number;
+      lightColor?: string;
+      camera?: { fov: number; near: number; far: number };
+      castShadow: boolean;
+      receiveShadow: boolean;
+    }
+  >;
+}
+
 /** Loop-gate hooks so a stable edit can pause the game that owns the rAF. */
 export interface IngestLoopControl {
   pause(): void;
@@ -115,9 +135,17 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
   /** Accumulated edits (this session + reapplied overlay), keyed by stable id. */
   private overlay: IngestOverlay = {};
   private dirty = false;
+  private readonly historyResource: JsonHistoryResource<IngestHistoryState> | null;
 
   readonly capabilities: AuthoringCapabilities;
 
+  readonly provenance: AuthoringProvenance = {
+    source: 'foreign',
+    label: 'overlay',
+    detail:
+      'Unmodified ingested game — edits persist to an editor overlay, never to the game source.',
+  };
+
   constructor(
     private readonly store: EditorStore,
     private readonly scene: THREE.Scene,
@@ -128,12 +156,6 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
     this.destination =
       opts.destination ?? (opts.persist ? '(ingest overlay)' : '(runtime-only — not persisted)');
     this.camera = opts.camera;
-    // T3.2 slice 2: this adapter IS the undo/redo target the editor-global
-    // timeline dispatches to for entries it records below (`pushUndo`).
-    // `ingest-mode.ts`'s `exitIngestMode()` unregisters it on teardown, so a
-    // Ctrl+Z reaching an entry from a since-uninstalled ingest session drops it
-    // (with a warn) instead of undoing against a stale live scene.
-    registerUndoAdapter(this);
     this.capabilities = {
       transform: true,
       material: true,
@@ -151,6 +173,33 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
     };
     this.refresh();
     if (opts.overlay) this.applyOverlay(opts.overlay);
+    const history = store.projectHistory;
+    this.historyResource = history
+      ? new JsonHistoryResource({
+          history,
+          kind: opts.persist ? 'overlay' : 'session-state',
+          scope: opts.persist ? 'project' : 'session',
+          ...(opts.persist
+            ? { location: (opts.destination ?? '.vgai/overlays/ingest.json').replace(/^\//, '') }
+            : { sessionId: `ingest-${crypto.randomUUID()}` }),
+          displayName: opts.destination ?? 'Ingest edits',
+          capture: () => this.captureHistoryState(),
+          // The snapshot carries a mirror of every live Object3D (the restore
+          // payload), but an ingested game is a RUNNING game that animates its
+          // own objects every frame — so the full snapshot stops matching a
+          // frame after it is taken. Only the OVERLAY is this resource's real
+          // content (it is what `serialize()`/`save()` writes to disk, and only
+          // editor edits touch it), so it alone decides "did something else
+          // change this resource?". Without this, every ingest transaction
+          // failed preflight with `content-conflict` and undo silently did
+          // nothing (issue #81).
+          conflictIdentity: (state) => state.overlay,
+          restore: async (state) => {
+            this.restoreHistoryState(state);
+            if (this.persistFn) await this.persistFn(this.overlay);
+          },
+        })
+      : null;
   }
 
   /**
@@ -231,6 +280,7 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
     return {
       id,
       label: o.name || o.type || 'Object3D',
+      role: 'entity',
       kind: kindOf(o),
       parentId,
       childIds: o.children.map((c) => this.idOf(c)!).filter(Boolean),
@@ -292,26 +342,22 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
     // The game owns this object's transform; the editor freezes the game loop so
     // its gizmo edit isn't overwritten next frame, then resumes on release.
     owner: (): TransformOwner => 'external',
-    beginEdit: (id) => {
+    beginEdit: () => {
+      this.historyResource?.assertCanMutate();
       this.loop?.pause();
-      this.editStartTransform = this.transforms.get(id); // snapshot for undo
+      this.editStartState = this.captureHistoryState();
     },
     apply: (id, t) => this.writeTransform(id, t),
     endEdit: (id) => {
       this.loop?.resume();
-      const prev = this.editStartTransform;
-      this.editStartTransform = undefined;
-      if (!prev) return;
-      const next = this.transforms.get(id);
-      this.pushUndo({
-        undo: () => this.writeTransform(id, prev),
-        redo: () => this.writeTransform(id, next),
-      });
+      this.recordHistory(`Transform ${this.byId.get(id)?.name || 'Object'}`, this.editStartState);
+      this.editStartState = undefined;
     },
   };
 
   /** Write a transform to the live object + record it in the overlay (no undo push). */
   private writeTransform(id: string, t: Transform): void {
+    this.historyResource?.assertCanMutate();
     const o = this.byId.get(id);
     if (!o) return;
     o.position.set(t.position[0], t.position[1], t.position[2]);
@@ -376,12 +422,10 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
       return undefined;
     },
     set: (id, path, value) => {
-      const prev = this.inspector.get(id, path); // snapshot for undo
+      this.historyResource?.assertCanMutate();
+      const before = this.captureHistoryState();
       this.writeProp(id, path, value);
-      this.pushUndo({
-        undo: () => this.writeProp(id, path, prev),
-        redo: () => this.writeProp(id, path, value),
-      });
+      this.recordHistory(`Set ${this.byId.get(id)?.name || 'Object'} ${path}`, before);
     },
   };
 
@@ -417,34 +461,87 @@ export class IngestAuthoringAdapter implements AuthoringAdapter {
   }
 
   // --- Overlay-backed undo/redo (feat-edit-undo for ingested games) ---
-  private readonly undoStack: Array<{ undo: () => void; redo: () => void }> = [];
-  private readonly redoStack: Array<{ undo: () => void; redo: () => void }> = [];
-  private editStartTransform: Transform | undefined;
-
-  private pushUndo(entry: { undo: () => void; redo: () => void }): void {
-    this.undoStack.push(entry);
-    this.redoStack.length = 0;
-    notifyUndoableOp(this); // T3.2 slice 2 — tag this op on the global timeline
+  private editStartState: IngestHistoryState | undefined;
+
+  /**
+   * Journal a before→after snapshot pair into project history, LOUDLY.
+   *
+   * A rejected `record(...)` means the edit IS applied to the live scene but has
+   * no history entry: it cannot be undone and will not survive a reload.
+   * Swallowing that (the previous `.catch(() => {})`) turned a persistence
+   * failure into silent data loss — the user sees their edit, then loses it with
+   * no indication anything went wrong.
+   */
+  private recordHistory(label: string, before: IngestHistoryState | undefined): void {
+    if (!this.historyResource || !before) return;
+    void this.historyResource
+      .record(label, before, this.captureHistoryState())
+      .catch((err: unknown) => {
+        editorConsole.error(
+          `[ingest] failed to journal "${label}" into project history — the edit is applied ` +
+            `but has no history entry (it cannot be undone and will not survive reload): ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
   }
 
-  undo(): boolean {
-    // `false` tells the undo timeline "couldn't act — put the entry back"
-    // (see UndoAdapter in ./undo-timeline.ts).
-    const e = this.undoStack.pop();
-    if (!e) return false;
-    e.undo();
-    this.redoStack.push(e);
-    this.store.notifyIngestEdit();
-    return true;
+  dispose(): void {
+    this.historyResource?.dispose();
+  }
+
+  private captureHistoryState(): IngestHistoryState {
+    const objects: IngestHistoryState['objects'] = {};
+    for (const [id, object] of this.byId) {
+      const material = colorMaterialOf(object);
+      const light = lightOf(object);
+      const camera = perspectiveCameraOf(object);
+      objects[id] = {
+        name: object.name,
+        visible: object.visible,
+        transform: this.transforms.get(id),
+        ...(material ? { color: `#${material.color.getHexString()}` } : {}),
+        ...(light
+          ? {
+              lightIntensity: light.intensity,
+              lightColor: `#${light.color.getHexString()}`,
+            }
+          : {}),
+        ...(camera ? { camera: { fov: camera.fov, near: camera.near, far: camera.far } } : {}),
+        castShadow: object.castShadow,
+        receiveShadow: object.receiveShadow,
+      };
+    }
+    return { overlay: structuredClone(this.overlay), objects };
   }
 
-  redo(): boolean {
-    const e = this.redoStack.pop();
-    if (!e) return false;
-    e.redo();
-    this.undoStack.push(e);
+  private restoreHistoryState(state: IngestHistoryState): void {
+    for (const [id, value] of Object.entries(state.objects)) {
+      const object = this.byId.get(id);
+      if (!object) continue;
+      object.name = value.name;
+      object.visible = value.visible;
+      object.position.fromArray(value.transform.position);
+      object.quaternion.fromArray(value.transform.rotation);
+      object.scale.fromArray(value.transform.scale);
+      if (value.color) colorMaterialOf(object)?.color.set(value.color);
+      const light = lightOf(object);
+      if (light) {
+        if (value.lightIntensity !== undefined) light.intensity = value.lightIntensity;
+        if (value.lightColor) light.color.set(value.lightColor);
+      }
+      const camera = perspectiveCameraOf(object);
+      if (camera && value.camera) {
+        camera.fov = value.camera.fov;
+        camera.near = value.camera.near;
+        camera.far = value.camera.far;
+        camera.updateProjectionMatrix();
+      }
+      object.castShadow = value.castShadow;
+      object.receiveShadow = value.receiveShadow;
+    }
+    this.overlay = structuredClone(state.overlay);
+    this.dirty = true;
     this.store.notifyIngestEdit();
-    return true;
   }
 
   // A class GETTER, not a field initializer: a field initializer runs before the

package/src/authoring/mount-failure-report.ts

@@ -11,7 +11,7 @@
  *
  * D-V5 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24 composite): a composite
  * manifest (one ingest world + siblings, `ingest-siblings.ts`) can fail
- * SEVERAL worlds independently in one mount attempt (a `default-three`
+ * SEVERAL roots independently in one mount attempt (a `default-three`
  * sibling, a throwing `default-react` sibling, …) — a single-slot "last
  * failure wins" model would silently drop every failure but the latest, the
  * exact F9 anti-pattern this module exists to close. This generalizes the
@@ -38,12 +38,12 @@
 
 /** One manifest world's mount failure — the exact fields the banner shows. */
 export interface MountFailureReport {
-  /** The failing world's manifest id (`ResolvedWorldEntry.id`), or the
+  /** The failing world's manifest id (`ResolvedAdapterRoot.id`), or the
    *  `?ingest=<id>` URL-fallback route's discovered game/folder id. */
   readonly worldId: string;
-  /** The world's render substrate kind (`ResolvedWorldEntry.kind`, e.g.
+  /** The world's render substrate kind (`ResolvedAdapterRoot.kind`, e.g.
    *  `'threejs'`/`'pixijs'`/`'react'`) — or, for the URL-fallback route
-   *  (which has no `ResolvedWorldEntry` to read a kind from), the same
+   *  (which has no `ResolvedAdapterRoot` to read a kind from), the same
    *  vocabulary inferred from which fixture glob resolved the id. */
   readonly kind: string;
   /** The resolved adapter identity (`ResolvedAdapter['identity']` — e.g.
@@ -55,7 +55,7 @@ export interface MountFailureReport {
 }
 
 /** D-V5: an ORDERED list now backs the slot (insertion order — the order
- *  worlds actually failed in, which for a composite's sibling loop is
+ *  roots actually failed in, which for a composite's sibling loop is
  *  manifest order). Every existing (wave-4) accessor below is a thin view
  *  over this same array — never a second, parallel source of truth. */
 let _reports: MountFailureReport[] = [];

package/src/authoring/provenance.ts

@@ -0,0 +1,41 @@
+/**
+ * Seam-level provenance resolution (spec 29 §5, docs/unified-world-editor/
+ * 29-hierarchy-philosophy.md): which {@link AuthoringProvenance} governs a
+ * given hierarchy node. Provenance is declared once per adapter and rendered
+ * at the seam (world group row / panel header); affordance code also reads it
+ * for the REASON string on a disabled operation ("the subject is present but
+ * the operation isn't" — the complement of spec 28's hide-when-absent rule).
+ *
+ * Rule zero: roots are resolved by ASKING the composite (`groupNodeId` /
+ * `ownerOf`), never by decoding adapter-minted id strings here.
+ */
+import type { AuthoringAdapter, AuthoringProvenance } from '@engine/adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+
+/**
+ * The provenance governing `nodeId` under the ACTIVE adapter: the owning
+ * child's declaration inside a composite (a `world:<id>` group row resolves
+ * to that world's own child), the adapter's own declaration otherwise.
+ * `null` when nothing was declared (the shell shows no badge and falls back
+ * to a generic reason — never fabricates a claim).
+ */
+export function provenanceForNode(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringProvenance | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter.provenance ?? null;
+  for (const child of adapter.childAdapters()) {
+    if (adapter.groupNodeId(child.worldId) === nodeId) return child.adapter.provenance ?? null;
+  }
+  const worldId = adapter.ownerOf(nodeId);
+  if (worldId === null) return null;
+  const owner = adapter.childAdapters().find((c) => c.worldId === worldId);
+  return owner?.adapter.provenance ?? null;
+}
+
+/** The reason string for an affordance that is present but unavailable —
+ *  the adapter's own explanation when it declared one, a plain honest
+ *  fallback when it didn't. */
+export function unavailableReason(provenance: AuthoringProvenance | null): string {
+  return provenance?.detail ?? "Not supported by this world's adapter.";
+}