@vgai/editor 0.2.0

package/src/inspector-section-registry.ts

@@ -0,0 +1,117 @@
+/**
+ * Inspector section-contribution registry (C2,
+ * docs/unified-world-editor/26-unified-editor-spec.md §4 C2) — the
+ * PERMANENT, sanctioned adapter-module seam for contributing rich React
+ * sections to the ONE inspector shell (`components/Inspector.tsx`, formerly
+ * `IngestPanels.tsx`'s `GenericInspector`). Mirrors
+ * `hierarchy-menu-registry.ts`'s `register(match, …)` / `get(ctx)` /
+ * `__resetForTest` pattern one-for-one — same "test the pure logic
+ * headlessly" convention (no jsdom in this repo's default `vitest.config.ts`
+ * `environment: 'node'`).
+ *
+ * The generic property grid (`PropertyDescriptor.group` →
+ * `inspector-property-grouping.ts`'s `groupProperties()` →
+ * `ingest-group-<id>` sub-sections, rendered by the shell) stays untouched
+ * and composes WITH this registry: registered sections render AFTER the
+ * grid, as siblings. A registration may `suppresses` one or more built-in
+ * shell blocks it fully replaces (e.g. the first-party threejs adapter's
+ * rich `ComponentsSection` suppresses the shell's thin `components` grid
+ * block) so a matched selection never double-renders the same affordance —
+ * see `authoring/first-party-inspector/register.tsx` for the sanctioned
+ * first-party usage and `authoring/ui-inspector-sections.tsx` for the UI
+ * adapter's.
+ *
+ * Engine stays React-free (D6): this module, every registration, and every
+ * `Section` component live in the editor package only.
+ */
+
+import type { AuthoringAdapter, EditorNode } from '@engine/adapter';
+import type { ComponentType } from 'react';
+
+/** Built-in shell blocks a matched registration may suppress (see
+ *  `components/Inspector.tsx`'s render order for exactly what each covers). */
+export type InspectorBuiltin =
+  | 'header' // name input + kind line
+  | 'transform' // Position/Scale AxisRows
+  | 'properties' // ungrouped + grouped (`ingest-group-*`) descriptor grid
+  | 'components' // the C1 components block (incl. its N/A fallback)
+  | 'stories' // the D4/B3 stories block
+  | 'environment'; // the no-selection ingest-env branch
+
+export interface InspectorSectionProps {
+  readonly adapter: AuthoringAdapter;
+  /** Selected node id; `null` in the no-selection (environment) state. */
+  readonly nodeId: string | null;
+}
+
+export interface InspectorSectionRegistration {
+  /** `node` is `null` when nothing is selected (environment state). */
+  readonly match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+  readonly Section: ComponentType<InspectorSectionProps>;
+  /** Built-in shell blocks this registration replaces (default: none). */
+  readonly suppresses?: readonly InspectorBuiltin[];
+  /** Optional panel-title override — first non-empty one (in registration
+   *  order, among MATCHED registrations) wins over the shell's default. */
+  readonly panelName?: string;
+}
+
+const registrations: InspectorSectionRegistration[] = [];
+
+// --- Change notification (W3, docs/DATA-TOOLS-DESIGN.md §7) ---------------
+// First-party registrations all happen at import time (main.tsx side
+// effects), before React ever renders — nothing needed to observe them. W3's
+// project inspector TOOLS register asynchronously (folder scan) and
+// re-register on HMR, while a selection may already be showing — so the one
+// inspector shell subscribes here (`useSyncExternalStore`-shaped, mirroring
+// `tool-loader.ts`'s registry store) and re-renders on any (un)registration.
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyRegistryChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to (un)registrations. Returns an unsubscribe function. */
+export function subscribeInspectorSectionRegistry(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function inspectorSectionRegistryVersion(): number {
+  return _version;
+}
+
+/**
+ * Register a section contribution. `match` decides whether this
+ * registration applies to a given selection (or the no-selection state);
+ * `Section` renders when it does. Returns an unregister function.
+ */
+export function registerInspectorSections(reg: InspectorSectionRegistration): () => void {
+  registrations.push(reg);
+  notifyRegistryChanged();
+  return () => {
+    const idx = registrations.indexOf(reg);
+    if (idx >= 0) {
+      registrations.splice(idx, 1);
+      notifyRegistryChanged();
+    }
+  };
+}
+
+/** Every registration whose `match` applies to `node`/`adapter`, in registration order. */
+export function matchedInspectorSections(
+  node: EditorNode | null,
+  adapter: AuthoringAdapter,
+): InspectorSectionRegistration[] {
+  return registrations.filter((r) => r.match(node, adapter));
+}
+
+/** Test-only reset (mirrors `__resetHierarchyMenuRegistryForTest`). */
+export function __resetInspectorSectionRegistryForTest(): void {
+  registrations.length = 0;
+  notifyRegistryChanged();
+}

package/src/interactive-edit-scope.ts

@@ -0,0 +1,34 @@
+/**
+ * Interactive-edit (undo-gesture) scope — the ONE thing the shared input
+ * primitives (`components/primitives/NumberInput.tsx` / `ColorInput.tsx`)
+ * need from the editor: "a continuous gesture (scrub / color drag) starts /
+ * ends now, coalesce it into a single undo step".
+ *
+ * Split out of `EditorContext.tsx` for W3 of `docs/DATA-TOOLS-DESIGN.md`
+ * (§3.4): the widget kit is a public export (`@editor/widgets`) that
+ * scaffolded PROJECTS typecheck — importing `EditorContext` (and through it
+ * `EditorStore` and most of the editor) from a widget would drag the whole
+ * editor source graph into every project's `tsc`. This module's closure is
+ * react-only; `EditorProvider` bridges it to the real store
+ * (`beginInteractiveEdit`/`endInteractiveEdit`).
+ *
+ * Widgets consume it optionally (`useInteractiveEditScope()` returns `null`
+ * outside a provider — e.g. the widget gallery, or a project tool rendered
+ * in some future host): no scope simply means no undo coalescing.
+ */
+
+import { createContext, useContext } from 'react';
+
+/** Begin/end a coalesced interactive edit gesture (one undo step). Both are
+ *  idempotent in the editor's implementation — safe to call defensively. */
+export interface InteractiveEditScope {
+  begin(): void;
+  end(): void;
+}
+
+export const InteractiveEditScopeContext = createContext<InteractiveEditScope | null>(null);
+
+/** The ambient gesture scope, or `null` when no host provides one. */
+export function useInteractiveEditScope(): InteractiveEditScope | null {
+  return useContext(InteractiveEditScopeContext);
+}

package/src/main.tsx

@@ -0,0 +1,23 @@
+import { registerSceneUIRenderer } from '@vgai/scene-ui/register-scene-ui';
+import { createRoot } from 'react-dom/client';
+// Adapter-module contribution-seam registrations (side-effect imports only):
+// the permanent escape hatch for first-party UI that isn't yet contract-
+// expressible (A2's hierarchy-menu-registry.ts: prefab Unpack/Open/Save-as
+// context-menu items, and (C3) the UI adapter's "Add UI Canvas" item; C2's
+// inspector-section-registry.ts: the first-party threejs adapter's rich
+// inspector sections, and the UI adapter's own — registered here so both are
+// live for the unified editor's scene-UI child (C3). `scene-ui-mode/ui-prefab-hierarchy-
+// menu.ts` (E1.c) is the scene-UI "Save as Prefab..." counterpart.
+import './authoring/first-party-hierarchy-menu';
+import './authoring/first-party-inspector/register';
+import './authoring/react-inspector-section';
+import './authoring/ui-hierarchy-menu';
+import './authoring/ui-inspector-sections';
+import './scene-ui-mode/ui-prefab-hierarchy-menu';
+import { AppRoot } from './components/AppRoot';
+
+// Wire the React UI runtime into the engine's scene-UI bridge so a scene's `ui`
+// tree renders at game-time (B1) — the engine itself stays React-free.
+registerSceneUIRenderer();
+
+createRoot(document.getElementById('editor-root')!).render(<AppRoot />);

package/src/manifest-project.ts

@@ -0,0 +1,43 @@
+/**
+ * Manifest-backed project detection for the play path — T3.3 slice 2 part C
+ * (docs/CLI-ON-FOLDER-DESIGN.md §1D).
+ *
+ * The dev server serves the project's RAW `vgai.game.json` at `/vgai.game.json`
+ * (editor-server.ts's project-file-serving middleware, mirroring how it
+ * special-cases `/project.json`) with no view synthesis — the browser parses
+ * it itself through the PURE half of the manifest loader (`loadGameManifest`,
+ * `@engine/manifest/load`), never `load-file.ts` (that needs `node:fs`, which
+ * has no place in a browser bundle).
+ */
+
+import { loadGameManifest, type ResolvedGameManifest } from '@engine/manifest/load';
+
+/**
+ * Fetch + parse the current project's manifest, or `null` if it has none
+ * (legacy `project.json`-only project — the raw-manifest route 404s, same as
+ * any other missing project-root file per editor-server.ts). A manifest that
+ * EXISTS but fails validation still throws (same fail-loud contract
+ * `loadGameManifest` always has) — never silently falls back.
+ */
+export async function fetchGameManifest(): Promise<ResolvedGameManifest | null> {
+  const res = await fetch('/vgai.game.json');
+  if (!res.ok) return null;
+  return loadGameManifest(await res.json());
+}
+
+/**
+ * A1 (edit mode, defect 2): fetch the RAW, UN-validated `vgai.game.json` JSON
+ * — or `null` when the project genuinely has none (the route 404s). Unlike
+ * {@link fetchGameManifest}, this NEVER throws on a schema violation: edit mode
+ * must tolerate a manifest with ONE bad world (e.g. an unknown `kind`) by
+ * surfacing that world as an error node (#18) while the VALID worlds declared
+ * alongside it still open — strict `loadGameManifest` would reject the whole
+ * file and make every declared world vanish. The caller (`edit-mode-authoring
+ * .ts`) reads `worlds[]` leniently; a genuinely absent manifest (this returns
+ * `null`) is the only case that synthesizes a single-world game.
+ */
+export async function fetchRawGameManifest(): Promise<unknown | null> {
+  const res = await fetch('/vgai.game.json');
+  if (!res.ok) return null;
+  return res.json();
+}

package/src/model-thumbnail.ts

@@ -0,0 +1,156 @@
+/**
+ * Offscreen Three.js renderer that generates thumbnail images for .glb/.gltf models.
+ *
+ * Usage:
+ *   const renderer = getModelThumbnailRenderer();
+ *   const dataUrl = await renderer.render('/assets/models/Robot.glb');
+ *   // dataUrl is a PNG data-URL string suitable for <img src="...">
+ *
+ * - Singleton: one renderer is shared across all callers.
+ * - Deduplicating: concurrent requests for the same URL share one render pass.
+ * - Cached: once rendered, the data URL is returned immediately.
+ * - Self-cleaning: each loaded GLTF is disposed after the thumbnail is captured.
+ */
+
+import { gltfLoader } from '@engine/loader';
+import * as THREE from 'three';
+
+const SIZE = 128;
+
+let instance: ModelThumbnailRenderer | null = null;
+
+class ModelThumbnailRenderer {
+  private renderer: THREE.WebGLRenderer;
+  private scene: THREE.Scene;
+  private camera: THREE.PerspectiveCamera;
+  private cache = new Map<string, string>();
+  private pending = new Map<string, Promise<string>>();
+  // Shared, DRACO-wired GLTFLoader (A2 / CB2). One-off previews call `.load()`
+  // directly (no caching/cloning) and dispose the result after capture, which is
+  // safe — each parse is independent of the shared asset-loaders GLTF cache.
+  private loader = gltfLoader;
+
+  constructor() {
+    const canvas = document.createElement('canvas');
+    canvas.width = SIZE;
+    canvas.height = SIZE;
+
+    this.renderer = new THREE.WebGLRenderer({
+      canvas,
+      alpha: true,
+      antialias: true,
+      preserveDrawingBuffer: true,
+    });
+    this.renderer.setSize(SIZE, SIZE);
+    this.renderer.setPixelRatio(1);
+    this.renderer.outputColorSpace = THREE.SRGBColorSpace;
+    this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    this.renderer.toneMappingExposure = 1.0;
+
+    this.scene = new THREE.Scene();
+
+    // Soft ambient fill
+    this.scene.add(new THREE.AmbientLight(0xffffff, 0.8));
+
+    // Key light (upper-right-front)
+    const key = new THREE.DirectionalLight(0xffffff, 1.5);
+    key.position.set(3, 5, 4);
+    this.scene.add(key);
+
+    // Fill light (lower-left, dimmer, warm)
+    const fill = new THREE.DirectionalLight(0xffeedd, 0.4);
+    fill.position.set(-3, -1, 2);
+    this.scene.add(fill);
+
+    this.camera = new THREE.PerspectiveCamera(35, 1, 0.01, 1000);
+  }
+
+  /** Render a thumbnail for the given model URL. Returns a PNG data-URL. */
+  async render(url: string): Promise<string> {
+    const cached = this.cache.get(url);
+    if (cached) return cached;
+
+    // Deduplicate concurrent requests for the same URL
+    const inflight = this.pending.get(url);
+    if (inflight) return inflight;
+
+    const promise = this._render(url);
+    this.pending.set(url, promise);
+    try {
+      return await promise;
+    } finally {
+      this.pending.delete(url);
+    }
+  }
+
+  private async _render(url: string): Promise<string> {
+    const group = await new Promise<THREE.Group>((resolve, reject) => {
+      this.loader.load(url, (gltf) => resolve(gltf.scene), undefined, reject);
+    });
+
+    this.scene.add(group);
+
+    // Auto-frame the camera around the model
+    const box = new THREE.Box3().setFromObject(group);
+    const center = box.getCenter(new THREE.Vector3());
+    const size = box.getSize(new THREE.Vector3());
+    const maxDim = Math.max(size.x, size.y, size.z) || 1;
+    const fovRad = (this.camera.fov * Math.PI) / 180;
+    const dist = (maxDim / (2 * Math.tan(fovRad / 2))) * 1.3; // 1.3× padding
+
+    // Position camera at a 3/4 angle (slightly above, rotated 30° from front)
+    this.camera.position.set(
+      center.x + dist * 0.65,
+      center.y + dist * 0.45,
+      center.z + dist * 0.65,
+    );
+    this.camera.lookAt(center);
+    this.camera.near = dist * 0.01;
+    this.camera.far = dist * 20;
+    this.camera.updateProjectionMatrix();
+
+    // Render
+    this.renderer.setClearColor(0x000000, 0);
+    this.renderer.clear();
+    this.renderer.render(this.scene, this.camera);
+    const dataUrl = this.renderer.domElement.toDataURL('image/png');
+
+    // Clean up the loaded GLTF to free GPU memory
+    this.scene.remove(group);
+    group.traverse((obj) => {
+      const mesh = obj as THREE.Mesh;
+      if (mesh.geometry) mesh.geometry.dispose();
+      if (mesh.material) {
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const mat of materials) {
+          // Dispose any textures attached to the material
+          if ('map' in mat && mat.map instanceof THREE.Texture) mat.map.dispose();
+          if ('normalMap' in mat && mat.normalMap instanceof THREE.Texture) mat.normalMap.dispose();
+          if ('emissiveMap' in mat && mat.emissiveMap instanceof THREE.Texture)
+            mat.emissiveMap.dispose();
+          if ('aoMap' in mat && mat.aoMap instanceof THREE.Texture) mat.aoMap.dispose();
+          if ('roughnessMap' in mat && mat.roughnessMap instanceof THREE.Texture)
+            mat.roughnessMap.dispose();
+          if ('metalnessMap' in mat && mat.metalnessMap instanceof THREE.Texture)
+            mat.metalnessMap.dispose();
+          mat.dispose();
+        }
+      }
+    });
+
+    this.cache.set(url, dataUrl);
+    return dataUrl;
+  }
+
+  dispose() {
+    this.renderer.dispose();
+    this.cache.clear();
+    instance = null;
+  }
+}
+
+/** Get (or create) the shared thumbnail renderer. */
+export function getModelThumbnailRenderer(): ModelThumbnailRenderer {
+  if (!instance) instance = new ModelThumbnailRenderer();
+  return instance;
+}