@vgai/engine 0.2.0 → 0.3.0

package/src/scene/asset-loaders.ts

@@ -1,5 +1,7 @@
 /**
- * Canonical GLTF / texture / animgraph load + cache layer (A2).
+ * Canonical GLTF / texture load + cache layer (A2). (Formerly also hosted the
+ * `.animgraph.json` loader — removed by E5; see
+ * packages/engine/src/animation/xstate-animation-binding.ts.)
  *
  * ONE place that owns the URL-keyed caches and the clone-safety contract, shared
  * by BOTH the engine runtime (scene-loader, create-runtime) AND the editor
@@ -22,9 +24,7 @@
 
 import * as THREE from 'three';
 import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
-import type { AnimGraphFile } from '../animation/anim-graph-types';
-import { AnimGraphFileSchema } from '../animation/schema';
-import { gltfLoader, resolveUrl, textureLoader } from '../loader';
+import { gltfLoader, textureLoader } from '../loader';
 import { SceneParseError } from './parse';
 import { setUserData } from './user-data';
 
@@ -33,7 +33,6 @@ const gltfCache = new Map<
   string,
   Promise<{ scene: THREE.Group; animations: THREE.AnimationClip[] }>
 >();
-const animGraphCache = new Map<string, Promise<AnimGraphFile>>();
 
 /** Load (and cache) a texture via the shared, prefix-aware TextureLoader. */
 export function loadTexture(url: string): THREE.Texture {
@@ -146,34 +145,10 @@ export function resolveGltfNode(
 }
 
 /**
- * Fetch (and cache) an animgraph JSON file via the shared prefix-aware fetch.
- * Validated via `AnimGraphFileSchema` (T4.6) — a malformed `.animgraph.json`
- * throws a `SceneParseError` naming the file, not a deep TypeError once the
- * bad data reaches `AnimGraph`/`LayerRuntime`.
- */
-export function loadAnimGraphData(src: string): Promise<AnimGraphFile> {
-  let cached = animGraphCache.get(src);
-  if (!cached) {
-    cached = fetch(resolveUrl(src))
-      .then((r) => {
-        if (!r.ok) throw new Error(`Failed to load animgraph: ${src}`);
-        return r.json();
-      })
-      .then((json) => {
-        const result = AnimGraphFileSchema.safeParse(json);
-        if (!result.success) throw new SceneParseError(result.error.issues, src);
-        return result.data;
-      });
-    animGraphCache.set(src, cached);
-  }
-  return cached;
-}
-
-/**
- * Clear the module-level GLTF / texture / animgraph caches. Call on full runtime
- * teardown (create-runtime fullCleanup / hot-reload) to release cached GPU
- * resources and avoid leaking across editor Play sessions. See the lifetime note
- * at the top of this file for why these are NOT cleared per scene load.
+ * Clear the module-level GLTF / texture caches. Call on full runtime teardown
+ * (create-runtime fullCleanup / hot-reload) to release cached GPU resources
+ * and avoid leaking across editor Play sessions. See the lifetime note at the
+ * top of this file for why these are NOT cleared per scene load.
  *
  * NOTE: the IBL/skybox env-map cache lives in scene-loader (it needs a
  * WebGLRenderer for PMREM); scene-loader's `clearAssetCaches` wraps this and
@@ -182,7 +157,6 @@ export function loadAnimGraphData(src: string): Promise<AnimGraphFile> {
 export function clearAssetCaches(): void {
   textureCache.clear();
   gltfCache.clear();
-  animGraphCache.clear();
 }
 
 /**
@@ -190,6 +164,6 @@ export function clearAssetCaches(): void {
  * test to assert caches stay bounded (one entry per distinct asset URL) across
  * repeated loads of the same scene, rather than growing per load.
  */
-export function assetCacheSizes(): { textures: number; gltf: number; animGraphs: number } {
-  return { textures: textureCache.size, gltf: gltfCache.size, animGraphs: animGraphCache.size };
+export function assetCacheSizes(): { textures: number; gltf: number } {
+  return { textures: textureCache.size, gltf: gltfCache.size };
 }

package/src/scene/asset-paths.ts

@@ -75,7 +75,6 @@ export function collectAssetPaths(
     if (e.particles?.material?.map) paths.add(e.particles.material.map);
 
     if (e.audio?.src) paths.add(e.audio.src);
-    if (e.animation?.animGraph) paths.add(e.animation.animGraph);
     if (e.prefab && isFilePrefab(e.prefab)) paths.add(e.prefab);
   });
 
@@ -102,7 +101,6 @@ function renameInEntity(e: SceneEntity, oldPath: string, newPath: string): void
   if (e.particles?.material?.map === oldPath) e.particles.material.map = newPath;
 
   if (e.audio?.src === oldPath) e.audio.src = newPath;
-  if (e.animation?.animGraph === oldPath) e.animation.animGraph = newPath;
   if (e.prefab === oldPath) e.prefab = newPath;
 }
 

package/src/scene/asset-ref-check.ts

@@ -0,0 +1,248 @@
+/**
+ * Shared asset-reference integrity check (B6 follow-up to B2 item #20,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B6).
+ *
+ * RELOCATED HERE (from `packages/vgai-cli/src/apply-diff.ts`, where it was
+ * originally built as `dereferenceNewAssetRefs`) so it can be shared by BOTH
+ * `vgai apply-diff` (the file-mode CLI verb) and the SDK's
+ * `project.scene.apply` operation (`packages/vgai-sdk/src/project/scene-operations.ts`)
+ * WITHOUT the SDK importing from the CLI — that would invert the intended
+ * dependency direction (CLI -> SDK -> engine, §3.4). The engine's scene layer
+ * is the correct shared home: both the CLI and the SDK already depend
+ * directly on `@vgai/engine/scene/*` for scene parsing/patching, so this
+ * module sits alongside `parse.ts`/`scene-apply.ts` as one more piece of
+ * scene-layer machinery neither caller re-implements.
+ *
+ * WHAT THIS CATCHES that schema validation alone does not: the Zod scene
+ * schema only checks that e.g. `materialRef` is a STRING — never that the
+ * string points at anything real. A diff introducing
+ * `materialRef: "materials/typo.mat.json"` (nonexistent, or present but
+ * malformed) passes ordinary scene/patch validation and would be written;
+ * the failure would otherwise only surface later, at runtime asset fetch.
+ * `dereferenceNewAssetRefs` closes that gap by re-resolving every asset
+ * reference the diff INTRODUCED (present in `result`, absent from
+ * `inputScene` — deliberately not pre-existing refs, so a scene with
+ * unrelated prior breakage can still receive an unrelated repair;
+ * `validate-scenes` remains the whole-project content gate) against disk,
+ * refusing the write if anything is missing or fails its own schema.
+ *
+ * Reference kinds and their treatment (unchanged from the original CLI-only
+ * implementation):
+ *   - Zod-validated (JSON formats with engine Zod schemas): `materialRef`
+ *     (.mat.json -> parseMaterialFile), `prefab` in its file-path form
+ *     (.prefab.json -> parsePrefabFile). Prefabs are validated ONE level
+ *     deep — the referenced prefab file itself must exist and parse; assets
+ *     IT references are that file's own concern. (`animation.animGraph` ->
+ *     AnimGraphFileSchema was removed by E5 — AnimGraph no longer exists.)
+ *   - Existence-checked only (binary formats with no Zod schema to parse
+ *     them through): gltf `mesh.src`, every material texture-map path
+ *     (including the nested clearcoat/transmission/sheen/iridescence groups),
+ *     `particles.material.map`, `audio.src`, `environment.skybox`.
+ *   - `.inputmap.json` is structurally out of scope: no `.vscn.json`/
+ *     `.prefab.json` field references an input map.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseMaterialFile, parsePrefabFile, SceneParseError } from './parse';
+import type { SceneEntity, SceneFile } from './scene-types';
+
+/** One asset reference found in a scene document: where it is + what it points at. */
+export interface AssetRef {
+  /** The authored path string (web-root-relative, optionally /-prefixed). */
+  path: string;
+  /** Human-readable field location for error messages, e.g. `entity "crate" field materialRef`. */
+  field: string;
+  kind: 'material' | 'prefab' | 'binary';
+}
+
+/**
+ * One asset reference that failed to dereference. `reason` is a one-line-or-
+ * more human-readable explanation (schema-validation failures may be
+ * multi-line); `field`/`path` mirror `AssetRef` and `diskPath` is the
+ * resolved absolute path that was checked, so every caller (CLI text report,
+ * SDK structured error data) can build its own presentation from the same
+ * facts without re-deriving them.
+ */
+export interface AssetRefError {
+  field: string;
+  path: string;
+  diskPath: string;
+  reason: string;
+}
+
+/** Material texture-map fields that hold image paths — top-level and nested feature groups. */
+const MATERIAL_MAP_KEYS = [
+  'map',
+  'normalMap',
+  'emissiveMap',
+  'aoMap',
+  'roughnessMap',
+  'metalnessMap',
+  'displacementMap',
+] as const;
+const MATERIAL_GROUP_MAP_KEYS: Record<string, readonly string[]> = {
+  clearcoat: ['clearcoatMap', 'clearcoatRoughnessMap'],
+  transmission: ['transmissionMap'],
+  sheen: ['sheenColorMap', 'sheenRoughnessMap'],
+  iridescence: ['iridescenceMap', 'iridescenceThicknessMap'],
+};
+
+/** Same file-path-vs-registry-id heuristic as `asset-paths.ts`. */
+function isFilePrefab(value: string): boolean {
+  return value.includes('/');
+}
+
+function entityLabel(e: SceneEntity): string {
+  return e.id ? `entity "${e.name}" (id ${e.id})` : `entity "${e.name}"`;
+}
+
+/** Collect every asset reference in a scene document (entities walked recursively + environment), labeled for error messages. */
+export function collectAssetRefs(doc: SceneFile): AssetRef[] {
+  const refs: AssetRef[] = [];
+
+  function walk(entities: SceneEntity[]): void {
+    for (const e of entities) {
+      const label = entityLabel(e);
+      if (e.mesh?.type === 'gltf' && e.mesh.src) {
+        refs.push({ path: e.mesh.src, field: `${label} field mesh.src`, kind: 'binary' });
+      }
+      if (e.material) {
+        const mat = e.material as Record<string, unknown>;
+        for (const key of MATERIAL_MAP_KEYS) {
+          const val = mat[key];
+          if (typeof val === 'string') {
+            refs.push({ path: val, field: `${label} field material.${key}`, kind: 'binary' });
+          }
+        }
+        for (const [group, keys] of Object.entries(MATERIAL_GROUP_MAP_KEYS)) {
+          const groupVal = mat[group];
+          if (groupVal && typeof groupVal === 'object') {
+            for (const key of keys) {
+              const val = (groupVal as Record<string, unknown>)[key];
+              if (typeof val === 'string') {
+                refs.push({
+                  path: val,
+                  field: `${label} field material.${group}.${key}`,
+                  kind: 'binary',
+                });
+              }
+            }
+          }
+        }
+      }
+      if (e.materialRef) {
+        refs.push({ path: e.materialRef, field: `${label} field materialRef`, kind: 'material' });
+      }
+      if (e.particles?.material?.map) {
+        refs.push({
+          path: e.particles.material.map,
+          field: `${label} field particles.material.map`,
+          kind: 'binary',
+        });
+      }
+      if (e.audio?.src) {
+        refs.push({ path: e.audio.src, field: `${label} field audio.src`, kind: 'binary' });
+      }
+      if (e.prefab && isFilePrefab(e.prefab)) {
+        refs.push({ path: e.prefab, field: `${label} field prefab`, kind: 'prefab' });
+      }
+      if (e.children) walk(e.children);
+    }
+  }
+
+  walk(doc.entities);
+  if (doc.environment?.skybox) {
+    refs.push({ path: doc.environment.skybox, field: 'environment.skybox', kind: 'binary' });
+  }
+  return refs;
+}
+
+/**
+ * Resolve the asset root the scene's references are relative to. Asset paths
+ * are web-root-relative (the runtime fetches them from the served `public/`
+ * directory), and scene files conventionally live INSIDE `public/`
+ * (`public/scenes/*.vscn.json`) — so the nearest ancestor directory literally
+ * named `public` is the root. Fallback for scenes not under a `public/`
+ * ancestor: the scene's own directory.
+ */
+export function findAssetRoot(scenePath: string): string {
+  const dir = resolve(dirname(scenePath));
+  let cursor = dir;
+  for (;;) {
+    if (basename(cursor) === 'public') return cursor;
+    const parent = dirname(cursor);
+    if (parent === cursor) return dir;
+    cursor = parent;
+  }
+}
+
+/** Format Zod/scene-parse issues as `path: message`, one per line. */
+function formatIssues(issues: { path: PropertyKey[]; message: string }[]): string {
+  return issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+}
+
+/**
+ * Dereference every asset reference `result` introduces relative to
+ * `inputScene` (present in the result, absent from the input) against disk,
+ * relative to `scenePath`'s asset root (see `findAssetRoot`). Returns
+ * structured errors (empty = every new reference resolved and validated) —
+ * never throws; callers decide how to present/escalate a non-empty result
+ * (the CLI folds these into one `ApplyDiffCliError` message, the SDK raises
+ * a declared `ASSET_REF_INVALID` `OperationError`).
+ */
+export function dereferenceNewAssetRefs(
+  inputScene: SceneFile,
+  result: SceneFile,
+  scenePath: string,
+): AssetRefError[] {
+  const preexisting = new Set(collectAssetRefs(inputScene).map((r) => r.path));
+  const newRefs = collectAssetRefs(result).filter((r) => !preexisting.has(r.path));
+  if (newRefs.length === 0) return [];
+
+  const assetRoot = findAssetRoot(scenePath);
+  const errors: AssetRefError[] = [];
+
+  for (const ref of newRefs) {
+    const diskPath = join(assetRoot, ref.path.replace(/^\//, ''));
+    if (!existsSync(diskPath)) {
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `file not found at ${diskPath} (resolved against ${assetRoot})`,
+      });
+      continue;
+    }
+    if (ref.kind === 'binary') continue; // existence-only (see the exclusion note above)
+
+    let json: unknown;
+    try {
+      json = JSON.parse(readFileSync(diskPath, 'utf-8'));
+    } catch (err) {
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `${diskPath} is not valid JSON: ${err instanceof Error ? err.message : err}`,
+      });
+      continue;
+    }
+    try {
+      if (ref.kind === 'material') {
+        parseMaterialFile(json, diskPath);
+      } else {
+        parsePrefabFile(json, diskPath);
+      }
+    } catch (err) {
+      const detail = err instanceof SceneParseError ? `\n${formatIssues(err.issues)}` : ` ${err}`;
+      errors.push({
+        field: ref.field,
+        path: ref.path,
+        diskPath,
+        reason: `${diskPath} fails schema validation:${detail}`,
+      });
+    }
+  }
+  return errors;
+}

package/src/scene/parse.ts

@@ -23,7 +23,138 @@ export class SceneParseError extends Error {
   }
 }
 
+// ---------------------------------------------------------------------------
+// D8 — removed-format migration guard: declarative property tracks
+// (`animation.tracks`) were deleted (spec §3.2/§10 D8; Theatre — `@theatre/core`
+// — is the sole authored continuous-animation source now). `SceneAnimationSchema`
+// no longer declares a `tracks` field at all (so the generated JSON schema stays
+// clean), which means Zod's default object mode would otherwise silently STRIP
+// an authored `animation.tracks` rather than reporting it — violating Global AC
+// §6 ("Removed formats fail with a concise migration/removal error rather than
+// being partially read"). This walks the RAW pre-Zod JSON (Zod would already
+// have stripped `tracks` by the time any schema-level check could see it) and
+// throws a `SceneParseError` before Zod ever parses the data. Matches on the
+// literal key `animation` (singular, an object) carrying a `tracks` property —
+// this is deliberately narrower than Scene UI's unrelated, RETAINED
+// `ui[].animations[].tracks` (plural `animations`), which this guard must not
+// trip on.
+// ---------------------------------------------------------------------------
+
+/** True when `value` is a plain object (not an array) carrying a `tracks` property — the shape
+ * `SceneAnimationSchema` used to declare before D8 deleted it. */
+function isRemovedTracksAnimation(value: unknown): boolean {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'tracks' in value;
+}
+
+function findRemovedPropertyTrackPathInArray(node: unknown[], path: string): string | undefined {
+  for (let i = 0; i < node.length; i++) {
+    const hit = findRemovedPropertyTrackPath(node[i], `${path}[${i}]`);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedPropertyTrackPathInObject(
+  obj: Record<string, unknown>,
+  path: string,
+): string | undefined {
+  if (isRemovedTracksAnimation(obj['animation'])) {
+    return `${path ? `${path}.` : ''}animation.tracks`;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const hit = findRemovedPropertyTrackPath(value, path ? `${path}.${key}` : key);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedPropertyTrackPath(node: unknown, path: string): string | undefined {
+  if (Array.isArray(node)) return findRemovedPropertyTrackPathInArray(node, path);
+  if (node && typeof node === 'object') {
+    return findRemovedPropertyTrackPathInObject(node as Record<string, unknown>, path);
+  }
+  return undefined;
+}
+
+function assertNoRemovedPropertyTracks(json: unknown, filePath?: string): void {
+  const hit = findRemovedPropertyTrackPath(json, '');
+  if (!hit) return;
+  const issue: ZodIssue = {
+    code: 'custom',
+    message:
+      'property tracks were removed; author continuous animation with Theatre (@theatre/core) ' +
+      'instead — see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.2/§10 D8.',
+    path: hit.split('.'),
+  };
+  throw new SceneParseError([issue], filePath);
+}
+
+// ---------------------------------------------------------------------------
+// E5 — removed-format migration guard: the AnimGraph state-machine runtime,
+// `.animgraph.json` format, and `SceneAnimationSchema.animGraph` field were
+// deleted (spec §3.3/§11 E5; XState + native Three `AnimationMixer` — see
+// `xstate-animation-binding.ts` — replace it). `SceneAnimationSchema` no
+// longer declares an `animGraph` field at all (so it carries zero trace in
+// the generated JSON schema), which means Zod's default object mode would
+// otherwise silently STRIP an authored `animation.animGraph` rather than
+// reporting it — violating Global AC §6. Mirrors
+// `assertNoRemovedPropertyTracks` above exactly: walks the RAW pre-Zod JSON
+// and throws a `SceneParseError` before Zod ever parses the data.
+// ---------------------------------------------------------------------------
+
+/** True when `value` is a plain object (not an array) carrying an `animGraph` property — the
+ * shape `SceneAnimationSchema` used to declare before E5 deleted it. */
+function isRemovedAnimGraphAnimation(value: unknown): boolean {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'animGraph' in value;
+}
+
+function findRemovedAnimGraphPathInArray(node: unknown[], path: string): string | undefined {
+  for (let i = 0; i < node.length; i++) {
+    const hit = findRemovedAnimGraphPath(node[i], `${path}[${i}]`);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedAnimGraphPathInObject(
+  obj: Record<string, unknown>,
+  path: string,
+): string | undefined {
+  if (isRemovedAnimGraphAnimation(obj['animation'])) {
+    return `${path ? `${path}.` : ''}animation.animGraph`;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const hit = findRemovedAnimGraphPath(value, path ? `${path}.${key}` : key);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+function findRemovedAnimGraphPath(node: unknown, path: string): string | undefined {
+  if (Array.isArray(node)) return findRemovedAnimGraphPathInArray(node, path);
+  if (node && typeof node === 'object') {
+    return findRemovedAnimGraphPathInObject(node as Record<string, unknown>, path);
+  }
+  return undefined;
+}
+
+function assertNoRemovedAnimGraph(json: unknown, filePath?: string): void {
+  const hit = findRemovedAnimGraphPath(json, '');
+  if (!hit) return;
+  const issue: ZodIssue = {
+    code: 'custom',
+    message:
+      'AnimGraph was removed; drive character animation with an XState animation machine instead ' +
+      '— see docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§5.6/§11 E5 and ' +
+      'packages/engine/src/animation/xstate-animation-binding.ts.',
+    path: hit.split('.'),
+  };
+  throw new SceneParseError([issue], filePath);
+}
+
 export function parseSceneFile(json: unknown, filePath?: string): SceneFile {
+  assertNoRemovedPropertyTracks(json, filePath);
+  assertNoRemovedAnimGraph(json, filePath);
   const result = SceneFileSchema.safeParse(json);
   if (!result.success) {
     throw new SceneParseError(result.error.issues, filePath);
@@ -36,6 +167,8 @@ export function parseSceneFile(json: unknown, filePath?: string): SceneFile {
 }
 
 export function parsePrefabFile(json: unknown, filePath?: string): PrefabFile {
+  assertNoRemovedPropertyTracks(json, filePath);
+  assertNoRemovedAnimGraph(json, filePath);
   const result = PrefabFileSchema.safeParse(json);
   if (!result.success) {
     throw new SceneParseError(result.error.issues, filePath);