@vgai/engine 0.5.2 → 0.5.4

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

@@ -1,248 +0,0 @@
-/**
- * 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` `ToolError`).
- */
-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/component-registry.ts

@@ -1,51 +0,0 @@
-import type * as THREE from 'three';
-import type { ComponentManager } from '../ecs/component-manager';
-import {
-  GAME_COMPONENT_BRAND,
-  GameComponent,
-  type GameComponentClass,
-} from '../ecs/game-component';
-
-/** A registry mapping component names to GameComponent classes. */
-export type ComponentRegistry = Record<string, GameComponentClass>;
-
-/** Type guard: is this value a GameComponent class? `instanceof` alone is NOT
- *  enough: a scaffolded project's node-side scripts resolve TWO physical
- *  copies of the engine (published `@vgai/engine/*` + the `@engine/*` source
- *  alias), and a class extending the OTHER copy's `GameComponent` fails the
- *  prototype-chain check — so this also accepts the cross-copy
- *  {@link GAME_COMPONENT_BRAND}. */
-export function isGameComponentClass(entry: unknown): entry is GameComponentClass {
-  if (typeof entry !== 'function') return false;
-  if (entry.prototype instanceof GameComponent) return true;
-  return (entry as unknown as Record<symbol, unknown>)[GAME_COMPONENT_BRAND] === true;
-}
-
-/**
- * Apply components from scene JSON data onto an entity (an Object3D).
- *
- * For each named component: look up its class in the registry, validate +
- * default the authored data through the optional `static schema` (Zod), assign
- * onto a fresh instance, and attach it via the ComponentManager (which wires the
- * Object3D + physics refs and queues init()).
- */
-export function applyComponents(
-  registry: ComponentRegistry,
-  object3D: THREE.Object3D,
-  components: Record<string, Record<string, unknown>>,
-  manager: ComponentManager,
-): void {
-  for (const [name, data] of Object.entries(components)) {
-    const Klass = registry[name];
-    if (!Klass) {
-      throw new Error(`Component "${name}" not found in registry`);
-    }
-    const parsed = Klass.schema ? Klass.schema.parse(data) : data;
-    const inst = new Klass();
-    Object.assign(inst, parsed);
-    // T5.4: record the registry name + raw authored data so a later `hotSwap`
-    // keys on this stable identity (not the live `constructor.name`) and can
-    // re-validate `data` against a NEW class version's schema.
-    manager.attach(object3D, inst, { key: name, props: data });
-  }
-}

package/src/scene/parse.ts

@@ -1,204 +0,0 @@
-import type { ZodIssue } from 'zod';
-import { checkSceneVersionInRange } from './scene-version';
-import type { InstancesFile, MaterialFile, PrefabFile, SceneFile } from './schema';
-import {
-  InstancesFileSchema,
-  MaterialFileSchema,
-  PrefabFileSchema,
-  SceneFileSchema,
-} from './schema';
-
-export class SceneParseError extends Error {
-  readonly issues: ZodIssue[];
-  /** The offending file's path/URL, when the caller knows it (T4.6). */
-  readonly filePath?: string | undefined;
-
-  constructor(issues: ZodIssue[], filePath?: string) {
-    const msg = issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
-    const header = filePath ? `Scene validation failed (${filePath}):` : 'Scene validation failed:';
-    super(`${header}\n${msg}`);
-    this.name = 'SceneParseError';
-    this.issues = issues;
-    this.filePath = filePath;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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);
-  }
-  // Post-Zod-parse range check (T2.3/D3 §1.E) — the Zod shape stays a bare
-  // `z.number()`; this is where the file-format `version` axis is actually
-  // read/enforced.
-  checkSceneVersionInRange(result.data.version, 'scene');
-  return result.data;
-}
-
-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);
-  }
-  checkSceneVersionInRange(result.data.version, 'prefab');
-  return result.data;
-}
-
-/**
- * Parse a `.mat.json` shared material asset (T4.6). Unlike scene/prefab files,
- * there is no version-range gate yet for this format — `MaterialFileSchema`'s
- * `version` field is RESERVED (see `schema-consumption-map.ts`).
- */
-export function parseMaterialFile(json: unknown, filePath?: string): MaterialFile {
-  const result = MaterialFileSchema.safeParse(json);
-  if (!result.success) {
-    throw new SceneParseError(result.error.issues, filePath);
-  }
-  return result.data;
-}
-
-/**
- * Parse a `.instances.json` instance-transform asset (F3,
- * docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Mirrors `parseMaterialFile` exactly —
- * no version-range gate (the format is a bare tuple array, no `version` field).
- */
-export function parseInstancesFile(json: unknown, filePath?: string): InstancesFile {
-  const result = InstancesFileSchema.safeParse(json);
-  if (!result.success) {
-    throw new SceneParseError(result.error.issues, filePath);
-  }
-  return result.data;
-}