@vgai/editor 0.2.0

package/src/authoring/embed-only-adapter.ts

@@ -0,0 +1,57 @@
+/**
+ * EmbedOnlyAuthoringAdapter — the honest FLOOR for an OPAQUE prebuilt bundle.
+ *
+ * When a game ships as a prebuilt bundle with its own inlined `three` (no shared
+ * module, no reachable global), the scene-capture trap can't see its renderer, so
+ * the editor cannot introspect or edit its scene. Per the founding docs
+ * (`ADAPTER-ARCHITECTURE.md` §2.3, coverage table: "prebuilt bundle, three opaque
+ * → iframe embed → tier 0–1") we still HOST it — run it in an iframe, size it,
+ * dispose it — but expose no authoring. This adapter advertises exactly that: an
+ * informational hierarchy node and all `capabilities` false, so the editor's
+ * generic panels render an honest "embed-only" state instead of pretending to edit.
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+} from '@engine/adapter';
+import type { EditorStore } from '../editor-store';
+
+const EMBED_ID = 'embed:root';
+
+export function makeEmbedOnlyAdapter(store: EditorStore, label: string): AuthoringAdapter {
+  const node: EditorNode = {
+    id: EMBED_ID,
+    label: `${label} (embed-only)`,
+    kind: 'object',
+    parentId: null,
+    childIds: [],
+    flags: { runtimeOnly: true, locked: true },
+  };
+  const hierarchy: HierarchyProvider = {
+    roots: () => [node],
+    node: (id) => (id === EMBED_ID ? node : null),
+    object3D: () => null, // opaque — no reachable Object3D
+    idForObject3D: () => null,
+  };
+  const capabilities: AuthoringCapabilities = {
+    transform: false,
+    material: false,
+    inspectorFields: false,
+    create: false,
+    delete: false,
+    reparent: false,
+    persist: false,
+  };
+  return {
+    capabilities,
+    hierarchy,
+    selection: {
+      get: () => [...store.selectedEntityIds],
+      set: (ids) => store.selectMultiple(ids),
+    },
+    subscribe: (listener) => store.subscribe(listener),
+  };
+}

package/src/authoring/ephemeral-persistence.ts

@@ -0,0 +1,26 @@
+/**
+ * Ephemeral persistence provider — for sessions whose edits must NOT survive past
+ * the session (play-mode's adoption of the live game scene; design
+ * `docs/PERSISTENCE-PROVIDER-DESIGN.md` §2/§7 slice 1).
+ *
+ * `isDirty()` is hard-coded `false`: nothing here is ever "unsaved" because there
+ * is nowhere for it to go — a no-op `save()` that pretended otherwise would lie in
+ * the save-status UI. Per the contract, the host never calls `save()` when
+ * `isDirty()` is false, so `save()` below is a documented no-op, not a silent
+ * swallow of a real write. `serialize()` still returns the live document so a
+ * future capture-style pull (design §6.5) can read it out.
+ */
+
+import type { PersistenceProvider } from '@engine/adapter';
+
+export function createEphemeralPersistence(getDoc: () => unknown): PersistenceProvider {
+  return {
+    isDirty: () => false,
+    save: async () => {
+      // Never called by the host (isDirty() is always false — see doc comment
+      // above). No-op: there is nothing to write, not a swallowed failure.
+    },
+    serialize: () => getDoc(),
+    destination: 'ephemeral (discarded on stop)',
+  };
+}

package/src/authoring/eyedropper-session.ts

@@ -0,0 +1,69 @@
+/**
+ * Eyedropper session (D3.d, docs/unified-world-editor/27-visual-react-editing.md
+ * §6 D3) — a module-level subscribable singleton bridging the C1 `ColorPicker`
+ * (mounted inside the Inspector panel) and the canvas (`WorldSelectionOverlay`),
+ * the two SIBLING React trees a "click the eyedropper button, then click
+ * somewhere on the canvas" gesture must cross when the native `EyeDropper` API
+ * is unavailable (the FALLBACK path this whole module exists for — see
+ * `ColorPicker.tsx`'s `handleEyedropper` and the `ColorSampleProvider` contract
+ * doc comment for why the native path needs none of this: it samples real
+ * rendered pixels itself).
+ *
+ * Mirrors `world-session-state.ts`'s "bare module singleton" shape, but keeps
+ * its OWN subscriber list (rather than piggybacking on `EditorStore.
+ * notifyIngestEdit`) since this is transient cross-panel UI state, not an
+ * authored/session toggle any editor-store snapshot needs to carry.
+ *
+ * Only ONE fallback pick can be in flight at a time — beginning a new one
+ * silently supersedes whatever was pending (mirrors the ColorPicker's own
+ * "one popover at a time" assumption; nothing today opens two eyedroppers at
+ * once).
+ */
+
+export type EyedropperApply = (color: string | null) => void;
+
+let activeApply: EyedropperApply | null = null;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const l of listeners) l();
+}
+
+/** Begin a fallback eyedropper session — `apply` is the widget's own
+ *  sampled-color callback, called exactly once when the session resolves
+ *  (`null` color means "cancelled", e.g. Escape — never a fabricated color). */
+export function beginEyedropperSession(apply: EyedropperApply): void {
+  activeApply = apply;
+  notify();
+}
+
+/** True while a fallback session is awaiting a canvas click/Escape. */
+export function isEyedropperSessionActive(): boolean {
+  return activeApply !== null;
+}
+
+/** Resolve the active session with a sampled color (or `null` to cancel),
+ *  then close it. A no-op if no session is active. */
+export function resolveEyedropperSession(color: string | null): void {
+  const apply = activeApply;
+  if (!apply) return;
+  activeApply = null;
+  notify();
+  apply(color);
+}
+
+/** Subscribe to session begin/end transitions — `WorldSelectionOverlay` binds
+ *  this via `useSyncExternalStore` so it re-renders (shows/hides the cursor
+ *  swatch) the instant a session starts or ends. */
+export function subscribeEyedropperSession(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Test-only reset (mirrors `world-session-state.ts`'s identical helper) —
+ *  drops any pending session and every subscriber so unit tests don't leak
+ *  state across cases. */
+export function _resetEyedropperSessionForTest(): void {
+  activeApply = null;
+  listeners.clear();
+}

package/src/authoring/first-party-hierarchy-menu.ts

@@ -0,0 +1,74 @@
+/**
+ * First-party hierarchy context-menu extras (A2 escape hatch — see
+ * `hierarchy-menu-registry.ts`'s header comment; C2 blesses this seam as
+ * permanent).
+ *
+ * Ports the prefab Unpack/Open/Save-as actions from the deleted
+ * `SceneHierarchy.tsx`'s `ContextMenu` (former lines :258-298) behind
+ * `registerHierarchyMenuItems`, so `GameHierarchy` (the contract-only shell)
+ * never needs to know `SceneEntity`/`prefab` exist. Imported once for its
+ * side effect at boot (`main.tsx`).
+ *
+ * Scoping: `store.getEntityById(nodeId)` only resolves ids that are actually
+ * first-party `.vscn` entities in THIS store's own document — a foreign
+ * ingest/boundary node id never matches, and a composite's FOCUSED
+ * first-party child (A1 multi-world edit mode) still resolves correctly,
+ * since it shares the same store. No `instanceof`/adapter-identity check
+ * needed.
+ */
+
+import { resolveUrl } from '@engine/loader';
+import { registerHierarchyMenuItems } from '../hierarchy-menu-registry';
+
+// Prefab Unpack/Open/Save-as — not yet contract-expressible (StructureProvider
+// has no "unpack"/"open source asset" verb, and InspectorProvider has no
+// notion of "this entity IS a prefab instance"); registered by the owning
+// adapter module (the C2-blessed pattern) rather than added as a new
+// contract verb.
+registerHierarchyMenuItems(
+  (ctx) => !!ctx.store.getEntityById(ctx.nodeId),
+  (ctx) => {
+    const entity = ctx.store.getEntityById(ctx.nodeId);
+    if (!entity) return [];
+    if (entity.prefab) {
+      const prefabPath = entity.prefab;
+      return [
+        {
+          label: 'Unpack Prefab',
+          action: () => {
+            fetch(resolveUrl(prefabPath))
+              .then((res) => (res.ok ? res.json() : null))
+              .then((prefab) => {
+                if (prefab) ctx.store.unpackPrefab(ctx.nodeId, prefab.root);
+              })
+              .catch(() => {
+                /* ignore */
+              });
+          },
+        },
+        {
+          label: 'Open Prefab',
+          color: '#60a5fa',
+          action: () => {
+            window.dispatchEvent(
+              new CustomEvent('editor:open-asset', { detail: { path: prefabPath } }),
+            );
+          },
+        },
+      ];
+    }
+    return [
+      {
+        label: 'Save as Prefab...',
+        color: '#60a5fa',
+        action: () => {
+          window.dispatchEvent(
+            new CustomEvent('editor:save-as-prefab', {
+              detail: { entityId: ctx.nodeId, name: entity.name },
+            }),
+          );
+        },
+      },
+    ];
+  },
+);

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

@@ -0,0 +1,118 @@
+/**
+ * First-party "+ Add Section…" menu (C2, docs/unified-world-editor/26-
+ * unified-editor-spec.md §4 C2) — verbatim from the deleted
+ * `components/InspectorPanel.tsx` (former :241-339). Adds a section (Audio/
+ * Physics/Shadow/Particles/Spline) to every selected entity that's missing
+ * it, via `store.batchMutate` (free undo via `_pushUndo`).
+ */
+
+import { defaultParticlesData } from '@engine/scene/particles-factory';
+import type { SectionProps } from '../../components/inspectors/multi-edit-utils';
+import { useEditorStore } from '../../EditorContext';
+
+type Entity = SectionProps['entities'][number];
+
+interface AddSectionItem {
+  label: string;
+  /** Returns true if the entity already has this section. */
+  has: (e: Entity) => boolean;
+  /** Default data to add. */
+  defaults: Partial<Entity> | ((entity: Entity, all: Entity[]) => Partial<Entity>);
+}
+
+const addSectionItems: AddSectionItem[] = [
+  {
+    label: 'Bone Attachment',
+    has: (e) => !!e.boneAttachment,
+    defaults: (entity, all) => ({
+      boneAttachment: {
+        target: all.find((candidate) => candidate.id && candidate.id !== entity.id)?.id ?? '',
+        bone: 'hand_r',
+      },
+    }),
+  },
+  {
+    label: 'Audio',
+    has: (e) => !!e.audio,
+    defaults: { audio: { spatial: true, volume: 1 } },
+  },
+  {
+    label: 'Physics',
+    has: (e) => !!e.physics,
+    defaults: { physics: { bodyType: 'fixed', collider: { type: 'cuboid' } } },
+  },
+  {
+    label: 'Shadow',
+    has: (e) => !!e.shadow,
+    defaults: { shadow: { enabled: true } },
+  },
+  {
+    label: 'Particles',
+    has: (e) => !!e.particles,
+    defaults: { particles: defaultParticlesData() },
+  },
+  {
+    label: 'Spline',
+    has: (e) => !!e.spline,
+    defaults: {
+      spline: {
+        curveType: 'centripetal' as const,
+        points: [
+          [0, 0, 0] as [number, number, number],
+          [1, 0, 1] as [number, number, number],
+          [2, 0, 0] as [number, number, number],
+        ],
+        closed: false,
+      },
+    },
+  },
+];
+
+export function AddSectionMenu({ entities, ids }: SectionProps) {
+  const store = useEditorStore();
+  // Show items where at least one selected entity is missing that section
+  const available = addSectionItems.filter((item) => entities.some((e) => !item.has(e)));
+  if (available.length === 0) return null;
+
+  return (
+    <div style={{ padding: '6px 8px' }}>
+      <select
+        onChange={(e) => {
+          const item = available.find((i) => i.label === e.target.value);
+          if (item) {
+            const all = store.allEntities();
+            store.batchMutate(ids, (entity) => {
+              if (!item.has(entity)) {
+                Object.assign(
+                  entity,
+                  typeof item.defaults === 'function' ? item.defaults(entity, all) : item.defaults,
+                );
+              }
+            });
+          }
+          e.target.value = '';
+        }}
+        value=""
+        style={{
+          width: '100%',
+          background: '#333',
+          color: '#c5c8ce',
+          border: '1px solid #444',
+          borderRadius: 3,
+          fontSize: 11,
+          padding: '3px 4px',
+          cursor: 'pointer',
+        }}
+      >
+        <option value="" disabled>
+          + Add Section...
+        </option>
+        {available.map((item) => (
+          <option key={item.label} value={item.label}>
+            {item.label}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}