@vgai/engine 0.2.0 → 0.3.0

package/src/scene/scene-loader.ts

@@ -3,8 +3,7 @@ import * as THREE from 'three';
 import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
 import type { BatchedRenderer } from 'three.quarks';
 import { initNavigation, NavMeshManager } from '../ai/navigation';
-import { AnimGraph } from '../animation/anim-graph';
-import { PropertyTrackRunner } from '../animation/property-track';
+import { buildClipMap } from '../animation/clip-map';
 import { log } from '../dev/logger';
 import type { ComponentManager } from '../ecs/component-manager';
 import type { GameComponentClass } from '../ecs/game-component';
@@ -14,7 +13,6 @@ import { type RenderScope, resolveRenderSettings } from '../render/render-settin
 import {
   assetCacheSizes,
   clearAssetCaches as clearSharedAssetCaches,
-  loadAnimGraphData,
   loadGLTF,
   resolveGltfNode,
 } from './asset-loaders';
@@ -46,18 +44,18 @@ import {
 import { isEntityRefSchema } from './schema/entity-ref';
 import { getUserData, setUserData } from './user-data';
 
-// GLTF / texture / animgraph load+cache logic lives in the shared ./asset-loaders
-// module (A2) so the editor and runtime share one cache + one clone-safety
-// contract. Only the IBL/skybox env-map cache stays here — it needs a
-// WebGLRenderer (PMREM), which the shared module deliberately doesn't depend on.
+// GLTF / texture load+cache logic lives in the shared ./asset-loaders module
+// (A2) so the editor and runtime share one cache + one clone-safety contract.
+// Only the IBL/skybox env-map cache stays here — it needs a WebGLRenderer
+// (PMREM), which the shared module deliberately doesn't depend on.
 const envTextureCache = new Map<string, THREE.Texture>();
 let pmremGenerator: THREE.PMREMGenerator | null = null;
 
 /**
- * Clear module-level asset caches (textures, GLTF scenes, anim graphs, IBL env
- * maps). Call on full runtime teardown to release cached GPU resources and avoid
- * leaking across editor Play sessions. Delegates the GLTF/texture/animgraph
- * caches to {@link clearSharedAssetCaches} and additionally frees the local
+ * Clear module-level asset caches (textures, GLTF scenes, IBL env maps). Call
+ * on full runtime teardown to release cached GPU resources and avoid leaking
+ * across editor Play sessions. Delegates the GLTF/texture caches to
+ * {@link clearSharedAssetCaches} and additionally frees the local
  * IBL env-map cache + PMREM generator.
  *
  * Lifetime / P1.8: these caches are intentionally module-level and persist
@@ -99,14 +97,12 @@ export function updateSceneLODs(scene: THREE.Scene, camera: THREE.Camera): void
 export function __assetCacheSizesForTest(): {
   textures: number;
   gltf: number;
-  animGraphs: number;
   env: number;
 } {
   const sizes = assetCacheSizes();
   return {
     textures: sizes.textures,
     gltf: sizes.gltf,
-    animGraphs: sizes.animGraphs,
     env: envTextureCache.size,
   };
 }
@@ -176,19 +172,6 @@ function createCurveFromSpline(spline: SceneSpline): THREE.CatmullRomCurve3 | nu
   );
 }
 
-function buildClipMap(
-  animations: THREE.AnimationClip[],
-  aliases?: Record<string, string>,
-): Map<string, THREE.AnimationClip> {
-  const clips = new Map<string, THREE.AnimationClip>();
-  for (const clip of animations) {
-    const raw = clip.name.split('|').pop()?.toLowerCase() ?? clip.name;
-    const name = aliases?.[raw] ?? raw;
-    clips.set(name, clip);
-  }
-  return clips;
-}
-
 export interface SceneLoadContext {
   scene: THREE.Scene;
   rapierWorld: RAPIER.World;
@@ -205,10 +188,6 @@ export interface SceneLoadContext {
   instancesFileCache?: Map<string, InstancesFile>;
   /** Supply an AudioListener (attached to camera) to enable audio entity spawning. */
   audioListener?: THREE.AudioListener;
-  /** AnimGraph registry keyed by Object3D. If provided, loader registers created
-   *  AnimGraphs here (and skips tickFns to avoid double-ticking with the global
-   *  animationSystem). */
-  animGraphs?: Map<THREE.Object3D, AnimGraph>;
   /** ComponentManager for instantiating GameComponent classes from scene data. */
   componentManager?: ComponentManager;
   /** three.quarks BatchedRenderer. If provided, particle systems declared on
@@ -351,15 +330,15 @@ function entityLabel(def: SceneEntity): string {
 // ---------------------------------------------------------------------------
 // T3.9 — bounded-concurrency asset prefetch.
 //
-// Child/asset fetches (prefab files, materials, GLTF models, animgraphs) used
-// to only ever happen inline, one at a time, inside the fully-sequential
+// Child/asset fetches (prefab files, materials, GLTF models) used to only
+// ever happen inline, one at a time, inside the fully-sequential
 // `spawnEntity` recursion — fine at ~20 assets, product-breaking at hundreds
 // (every fetch's network round-trip is paid serially). Rather than restructure
 // the deterministic sequential spawn walk itself (which authored array order,
 // tickFns/mixers order, and GameComponent registration order all depend on),
 // this prefetch pass walks the WHOLE entity tree up front and warms the
-// existing URL-keyed caches (asset-loaders.ts's module-level GLTF/animgraph
-// caches, and this module's ctx-level prefab/material file caches) with a
+// existing URL-keyed caches (asset-loaders.ts's module-level GLTF cache, and
+// this module's ctx-level prefab/material file caches) with a
 // small concurrency limiter. The sequential spawn pass below is completely
 // unchanged — its `await`s just resolve instantly against a warm cache, so
 // wall-clock time is bounded by ceil(assetCount / limit) round-trips instead
@@ -416,10 +395,6 @@ function collectPrefetchTasks(
     const ref = def.materialRef;
     tasks.push(() => loadMaterialFile(ref, ctx));
   }
-  if (def.animation?.animGraph) {
-    const graph = def.animation.animGraph;
-    tasks.push(() => loadAnimGraphData(graph));
-  }
   if (def.prefab && !ctx.prefabs?.has(def.prefab) && !seenPrefabUrls.has(def.prefab)) {
     const prefabUrl = def.prefab;
     seenPrefabUrls.add(prefabUrl);
@@ -502,6 +477,12 @@ async function instantiateScene(
     ctx.scene.add(obj);
   }
 
+  // Pass 1.5: animated attachments must resolve only after every entity and
+  // GLTF skeleton has spawned. Reparenting preserves the authored transform
+  // as the local socket offset; gameplay components remain on the same
+  // Object3D and therefore require no mirror or adapter entity.
+  resolveBoneAttachments(data.entities, idMap);
+
   // Pass 2: create joints between physics bodies
   createSceneJoints(data.entities, idMap, ctx);
 
@@ -714,40 +695,33 @@ async function spawnEntity(
       wrapper.add(content);
       object3d = wrapper;
 
-      // Set up animation if defined
+      // Set up animation if defined. Always build the mixer + clip map (and
+      // expose both via userData) whenever the entity has clips — not just
+      // when `autoplay` is set — so a GameComponent (e.g. an XState-driven
+      // character controller, E5's replacement for the removed AnimGraph) can
+      // pick up `_animMixer`/`_animClips` in its own `init()` and drive the
+      // SAME mixer via `bindXStateAnimation` (xstate-animation-binding.ts).
+      // Only `autoplay` self-ticks here (`tickFns`) — a component driving its
+      // own binding calls `mixer.update(dt)` itself (inside the binding's
+      // `tick`), so auto-ticking unconditionally would double-advance it.
       if (def.animation && animations.length > 0) {
         const clipMap = buildClipMap(animations, def.animation.clipAliases);
+        const mixer = new THREE.AnimationMixer(gltfScene);
+        setUserData(object3d, '_animMixer', mixer);
+        setUserData(object3d, '_animClips', clipMap);
+        setUserData(object3d, '_availableClips', [...clipMap.keys()]);
+        mixers.push(mixer);
 
-        if (def.animation.animGraph) {
-          // Full AnimGraph state machine
-          const graphData = await loadAnimGraphData(def.animation.animGraph);
-          const mixer = new THREE.AnimationMixer(gltfScene);
-          const graph = new AnimGraph(mixer, graphData, clipMap);
-          if (def.animation.parameters) {
-            for (const [key, value] of Object.entries(def.animation.parameters)) {
-              graph.setParameter(key, value);
-            }
-          }
-          if (ctx.animGraphs) {
-            // Register in global map (keyed by Object3D); animationSystem ticks it.
-            ctx.animGraphs.set(object3d, graph);
-          } else {
-            // Standalone: tick via scene instance update
-            tickFns.push((dt) => graph.update(dt));
-          }
-          mixers.push(mixer);
-        } else if (def.animation.autoplay) {
+        if (def.animation.autoplay) {
           // Simple clip autoplay
           const clip = clipMap.get(def.animation.autoplay);
           if (clip) {
-            const mixer = new THREE.AnimationMixer(gltfScene);
             const action = mixer.clipAction(clip);
             const loop = def.animation.loop ?? DEFAULTS.animation.loop;
             action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
             action.clampWhenFinished = !loop;
             action.play();
             tickFns.push((dt) => mixer.update(dt));
-            mixers.push(mixer);
           }
         }
       }
@@ -914,17 +888,6 @@ async function spawnEntity(
   // Visibility (mirrors editor: visible unless explicitly false)
   object3d.visible = def.visible ?? DEFAULTS.entity.visible;
 
-  // F5 — declarative property tracks (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md).
-  // Unlike gltf autoplay/animGraph above (clip-driven, gltf-only), tracks work
-  // on ANY entity — a box, a light, no gltf/clips required — so this lives
-  // OUTSIDE the gltf branch. Registered in the same tickFns list the
-  // AnimationMixers use, so it ticks on the same deterministic dt (honors
-  // pause/timeScale for free — no new clock).
-  if (def.animation?.tracks?.length) {
-    const runner = new PropertyTrackRunner(object3d, def.animation.tracks);
-    tickFns.push((dt) => runner.update(dt));
-  }
-
   // Physics — stores {body, collider} in the physics registry keyed by object3d.
   // T1.1: the body is created at the COMPOSED WORLD transform (ancestorCtx's
   // world matrix × this entity's own local transform), not the raw authored
@@ -1161,6 +1124,42 @@ function walkEntities(entities: SceneEntity[], fn: (e: SceneEntity) => void): vo
   }
 }
 
+/** Reparent scene-authored entities to named bones/sockets in loaded GLTF skeletons. */
+function resolveBoneAttachments(entities: SceneEntity[], idMap: Map<string, THREE.Object3D>): void {
+  walkEntities(entities, (def) => {
+    const attachment = def.boneAttachment;
+    if (!attachment || !def.id) return;
+
+    const object = idMap.get(def.id);
+    if (!object) return;
+    const target = idMap.get(attachment.target);
+    if (!target) {
+      throw new Error(
+        `Bone attachment target "${attachment.target}" not found for entity "${entityLabel(def)}".`,
+      );
+    }
+    if (target === object) {
+      throw new Error(`Entity "${entityLabel(def)}" cannot attach to its own skeleton.`);
+    }
+
+    const socket = target.getObjectByName(attachment.bone);
+    if (!socket) {
+      const available: string[] = [];
+      target.traverse((node) => {
+        if (node.name && node instanceof THREE.Bone) {
+          available.push(node.name);
+        }
+      });
+      const suffix = available.length > 0 ? ` Available bones: ${available.sort().join(', ')}` : '';
+      throw new Error(
+        `Bone/socket "${attachment.bone}" was not found on target "${attachment.target}" for entity "${entityLabel(def)}".${suffix}`,
+      );
+    }
+
+    socket.add(object);
+  });
+}
+
 /** Create Rapier joints for all entities that define them. */
 function createSceneJoints(
   entities: SceneEntity[],
@@ -1370,10 +1369,10 @@ export interface SpawnedPrefab {
   /** The Object3D of the spawned prefab root (added to the scene). */
   object3D: THREE.Object3D;
   /**
-   * Tick standalone (non-animGraph) animations for this prefab — e.g. a simple
-   * `animation.autoplay` clip. AnimGraphs are registered into `ctx.animGraphs`
-   * (when provided) and ticked by the global animationSystem instead, so this
-   * is a no-op for those. Call once per frame, mirroring SceneInstance.update.
+   * Tick standalone `animation.autoplay` clips for this prefab. A GameComponent
+   * that attaches its own XState-driven animation binding (E5 — see
+   * `xstate-animation-binding.ts`) ticks that binding itself, so this is a
+   * no-op for those. Call once per frame, mirroring SceneInstance.update.
    */
   update(dt: number): void;
   /** Stop any mixers this prefab created. */
@@ -1385,16 +1384,16 @@ export interface SpawnedPrefab {
  *
  * Returns a {@link SpawnedPrefab}. The previous version passed throwaway
  * tickFns/mixers arrays, so a runtime-spawned prefab's `animation.autoplay`
- * (or an animGraph with no `ctx.animGraphs`) never advanced. Now the tick
- * functions are captured and exposed via `update()`, consistent with how
- * loadScene's SceneInstance.update drives animations.
+ * never advanced. Now the tick functions are captured and exposed via
+ * `update()`, consistent with how loadScene's SceneInstance.update drives
+ * animations.
  *
  * Usage:
  *   const crate = await spawnPrefab('/data/prefabs/crate.prefab.json', ctx, {
  *     transform: { position: [x, y, z] },
  *     components: { Health: { current: 50 } },
  *   });
- *   // each frame (only needed for autoplay clips; animGraphs tick globally):
+ *   // each frame (only needed for autoplay clips):
  *   crate.update(dt);
  */
 export async function spawnPrefab(
@@ -1445,13 +1444,8 @@ export async function spawnPrefab(
     //  - mixers (THREE.AnimationMixer, simple `animation.autoplay` clips)
     //    DISPOSED — stopAllAction() on every mixer this spawn created
     //    (pre-existing).
-    //  - tickFns (standalone animGraph/mixer tick closures, only used when
-    //    `ctx.animGraphs` is NOT provided)   DISPOSED — array cleared so
-    //    update() becomes a no-op (pre-existing).
-    //  - ctx.animGraphs (Object3D -> AnimGraph, when provided)
-    //    NEWLY-DISPOSED — every entry whose key is inside the spawned
-    //    subtree is deleted, so the global animationSystem stops ticking a
-    //    despawned graph (probe1: previously leaked forever).
+    //  - tickFns (standalone `animation.autoplay` mixer tick closures)
+    //    DISPOSED — array cleared so update() becomes a no-op (pre-existing).
     //  - ctx.particleRenderer (three.quarks BatchedRenderer, when provided)
     //    NEWLY-DISPOSED — every particle system tagged via the
     //    `_particleSystem` userData key (mirrors editor scene-sync's own
@@ -1469,7 +1463,7 @@ export async function spawnPrefab(
     //    tags on Object3Ds that get garbage-collected with the subtree once
     //    `ctx.scene.remove(object3D)` drops the last reference; there is no
     //    separate ctx-level registry entry to leak.
-    //  - GLTF/texture/animgraph asset caches (asset-loaders.ts, module-level)
+    //  - GLTF/texture asset caches (asset-loaders.ts, module-level)
     //    DELIBERATELY NOT DISPOSED — these are shared, URL-keyed caches
     //    across the whole runtime session (P1.8 contract: repeated
     //    spawns/loads of the same asset must NOT re-fetch or re-parse), not
@@ -1492,15 +1486,6 @@ export async function spawnPrefab(
         ctx.rapierWorld.removeRigidBody(refs.body);
         ctx.physics.remove(node);
       });
-      // Unregister any AnimGraphs this subtree registered into the shared,
-      // Object3D-keyed ctx.animGraphs map — otherwise the global
-      // animationSystem keeps ticking a despawned graph forever.
-      if (ctx.animGraphs) {
-        const animGraphs = ctx.animGraphs;
-        object3D.traverse((node) => {
-          animGraphs.delete(node);
-        });
-      }
       // Unregister any particle systems this subtree registered with the
       // shared BatchedRenderer — otherwise they keep simulating/rendering
       // after the visual object is gone. `_particleSystem` is the same

package/src/scene/schema/animation.ts

@@ -1,94 +1,45 @@
 import { z } from 'zod';
-// Reuse the UI track easing vocabulary (S1) so there is ONE easing enum across
-// the codebase — see F5 (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Do NOT reuse
-// UIKeyframeSchema itself: its `value` is `z.union([z.number(), z.string()])`,
-// and property-track values MUST be numbers only (no expression/string-logic
-// values — in-scene scripting is banned, G1).
-import { UIEasingSchema } from './ui';
-
-/** Validated at runtime against AnimGraph parameter definitions. */
-const AnimParameterOverridesSchema = z.record(z.string(), z.union([z.number(), z.boolean()]));
 
 // ---------------------------------------------------------------------------
-// F5 — Declarative property tracks (deterministic timeline).
+// D8 — declarative property tracks (formerly F5,
+// docs/VSCN-STRUCTURAL-GAPS-DESIGN.md) were REMOVED: Theatre
+// (`@theatre/core`) is the sole authored continuous-animation source (spec
+// §3.2, §10 D2-D4/D8). `PropertyTrackSchema`/`PropertyTrackRunner` and the
+// `tracks` field are deleted, not deprecated-in-place — see
+// packages/engine/src/scene/parse.ts (`assertNoRemovedPropertyTracks`) for
+// the loud migration-error guard that rejects any `.vscn`/`.prefab.json`
+// still authoring `animation.tracks`, since Zod would otherwise silently
+// strip an unrecognized field rather than failing loudly (Global AC §6).
+//
+// E5 — the AnimGraph state-machine runtime, `.animgraph.json` format, and
+// every consumer were removed (spec §3.3, §11 E5; XState + native Three
+// `AnimationMixer` replace it — see `xstate-animation-binding.ts`). The
+// `animGraph` field is deleted outright, not deprecated-in-place, for the
+// same reason as `tracks` above: Zod's default object mode would otherwise
+// silently STRIP an authored `animation.animGraph` rather than reporting it,
+// violating Global AC §6 ("Removed formats fail with a concise migration/
+// removal error rather than being partially read"). The raw-JSON guard
+// (`assertNoRemovedAnimGraph` in packages/engine/src/scene/parse.ts) rejects
+// any `.vscn`/`.prefab.json` still authoring it before Zod ever parses the
+// data — see packages/engine/test/anim-graph-removed.test.ts.
 //
-// A track is DATA: a pure function of time (keyframes + named easing), never
-// behavior. `target` is a FIXED allowlist, not an arbitrary property path —
-// this is the guardrail that keeps the format from becoming an in-scene
-// scripting surface (G1, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md). Anything
-// state-dependent ("move WHEN the player steps on it") stays a GameComponent,
-// which may start/stop/seek a track — it never grows conditionals here.
+// `parameters` is deleted alongside `animGraph`, though it isn't itself named
+// in the spec/removal-inventory: its ONLY documented purpose was seeding an
+// `AnimGraph`'s initial parameter values (its only readers were
+// `scene-loader.ts`'s former animGraph branch, the editor's entity-factory.ts,
+// and AnimationSection.tsx's parameter-row UI — all deleted with the runtime).
+// Leaving it declared with zero remaining readers would violate this repo's
+// "no schema field without a runtime reader" policy (CLAUDE.md).
 // ---------------------------------------------------------------------------
 
-export const PropertyTrackTargetSchema = z
-  .enum([
-    'position.x',
-    'position.y',
-    'position.z',
-    'rotation.x',
-    'rotation.y',
-    'rotation.z',
-    'scale.x',
-    'scale.y',
-    'scale.z',
-    'material.opacity',
-    'light.intensity',
-  ])
-  .describe(
-    'The Object3D property this track drives. A FIXED allowlist, not an arbitrary property ' +
-      'path — an open path would let scene data address/mutate arbitrary runtime state, which ' +
-      'is in-scene scripting (banned, G1). Add new targets here deliberately, one at a time.',
-  );
-export type PropertyTrackTarget = z.infer<typeof PropertyTrackTargetSchema>;
-
-export const PropertyTrackKeyframeSchema = z
-  .object({
-    time: z.number().describe('Seconds from track start'),
-    value: z
-      .number()
-      .describe(
-        'Numeric value at this time — numbers only; no expressions/strings (in-scene scripting is banned)',
-      ),
-    easing: UIEasingSchema.optional().describe(
-      'Easing of the segment after this keyframe (reuses the UI track easing vocabulary)',
-    ),
-  })
-  .describe('A single keyframe (time + numeric value + optional easing) on a property track');
-export type PropertyTrackKeyframe = z.infer<typeof PropertyTrackKeyframeSchema>;
-
-export const PropertyTrackSchema = z
-  .object({
-    target: PropertyTrackTargetSchema,
-    keyframes: z.array(PropertyTrackKeyframeSchema).describe('Ordered by time'),
-    loop: z.boolean().optional().describe('Whether the track repeats after reaching `duration`'),
-    duration: z.number().describe('Track length in seconds'),
-  })
-  .describe('A deterministic keyframed timeline driving one allowlisted property');
-export type PropertyTrack = z.infer<typeof PropertyTrackSchema>;
-
 export const SceneAnimationSchema = z
   .object({
-    animGraph: z.string().optional().describe('Path to .animgraph.json state machine file'),
-    parameters: AnimParameterOverridesSchema.optional().describe(
-      'Initial parameter values for the animation graph',
-    ),
-    autoplay: z
-      .string()
-      .optional()
-      .describe('Clip name to play automatically on load (when no animGraph is set)'),
+    autoplay: z.string().optional().describe('Clip name to play automatically on load'),
     loop: z.boolean().optional().describe('Whether the autoplay clip should loop'),
     clipAliases: z
       .record(z.string(), z.string())
       .optional()
-      .describe('Map raw GLTF clip names to clean names used by the animation graph'),
-    tracks: z
-      .array(PropertyTrackSchema)
-      .optional()
-      .describe(
-        'Deterministic keyframed property timelines (data, not behavior — pure function of ' +
-          'time; state-dependent motion stays a GameComponent). Runs in the animation phase, ' +
-          'honors pause/timeScale.',
-      ),
+      .describe('Map raw GLTF clip names to clean names'),
   })
   .describe('Animation playback configuration');
 

package/src/scene/schema/entity.ts

@@ -13,6 +13,15 @@ import { SceneShadowOverrideSchema, SceneShadowSchema } from './shadow';
 import { SceneSplineOverrideSchema, SceneSplineSchema } from './spline';
 import { TransformSchema, Vec3Schema } from './tuples';
 
+const BoneAttachmentSchema = z
+  .object({
+    target: z.string().describe('Entity ID whose animated skeleton owns the target bone'),
+    bone: z.string().describe('Exact name of the target bone or socket Object3D'),
+  })
+  .describe(
+    'Attach this entity to a named bone/socket after the complete scene has loaded. The entity transform becomes its local attachment offset',
+  );
+
 /**
  * User-defined ECS component data. Validated at runtime against ComponentRegistry.
  *
@@ -65,6 +74,9 @@ const SharedEntityFields = {
     .optional()
     .describe('Path to shared .mat.json material asset. Mutually exclusive with inline material'),
   transform: TransformSchema.optional().describe('Local transform relative to parent'),
+  boneAttachment: BoneAttachmentSchema.optional().describe(
+    'Animated bone/socket attachment. Use transform for the local position, rotation, and scale offset',
+  ),
   pivot: Vec3Schema.optional().describe(
     'Local-space pivot point for rotation/scale. [0,0,0] = geometry center',
   ),
@@ -165,5 +177,13 @@ export const SceneEntitySchema: z.ZodType<SceneEntity> = z.lazy(() =>
           path: ['material'],
         });
       }
+      if (entity.boneAttachment !== undefined && entity.physics !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'A bone-attached entity cannot declare physics. Attachments follow an animated transform; add gameplay collision to a separate entity.',
+          path: ['boneAttachment'],
+        });
+      }
     }),
 ) as z.ZodType<SceneEntity>;

package/src/scene/schema/index.ts

@@ -1,17 +1,7 @@
 // Zod schemas
 
-export type {
-  PropertyTrack,
-  PropertyTrackKeyframe,
-  PropertyTrackTarget,
-  SceneAnimation,
-} from './animation';
-export {
-  PropertyTrackKeyframeSchema,
-  PropertyTrackSchema,
-  PropertyTrackTargetSchema,
-  SceneAnimationSchema,
-} from './animation';
+export type { SceneAnimation } from './animation';
+export { SceneAnimationSchema } from './animation';
 export type { SceneAudio } from './audio';
 export { SceneAudioSchema } from './audio';
 export type { SceneCamera } from './camera';

package/src/scene/user-data.ts

@@ -36,9 +36,12 @@
  *
  * Animation (load-bearing — ED5 disposal contract):
  * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
- * - `_animGraph`          — live AnimGraph instance (state machine) for this entity.
- * - `_animGraphData`      — the AnimGraphFile the graph was built from (inspector cache).
- * - `_availableClips`     — string[] of clip names discovered on the GLTF.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
+ *                           lets a GameComponent build its own XState-driven
+ *                           binding via `bindXStateAnimation` over the SAME
+ *                           mixer; see xstate-animation-binding.ts).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
  *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
@@ -81,8 +84,6 @@
 
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
-import type { AnimGraph } from '../animation/anim-graph';
-import type { AnimGraphFile } from '../animation/anim-graph-types';
 import type { SceneEntity } from './scene-types';
 
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
@@ -112,8 +113,7 @@ export interface UserDataSchema {
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
   _animMixer: THREE.AnimationMixer;
-  _animGraph: AnimGraph;
-  _animGraphData: AnimGraphFile;
+  _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
@@ -152,8 +152,7 @@ export const UserDataKeys = {
   _camera: '_camera',
   _particleSystem: '_particleSystem',
   _animMixer: '_animMixer',
-  _animGraph: '_animGraph',
-  _animGraphData: '_animGraphData',
+  _animClips: '_animClips',
   _availableClips: '_availableClips',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',

package/src/setup/setup-renderer.ts

@@ -86,6 +86,11 @@ export function createHostRenderer(
   rendering?: RenderScope,
   opts?: { alpha?: boolean; preserveDrawingBuffer?: boolean },
 ): THREE.WebGLRenderer {
+  // A newly-shown editor tab can report 0x0 for one layout frame. WebGL render
+  // targets cannot have zero-sized attachments, so boot at the smallest valid
+  // backing size and let the normal resize path apply the real dimensions.
+  const safeWidth = Math.max(1, width);
+  const safeHeight = Math.max(1, height);
   const settings = resolveRenderSettings(rendering);
   const renderer = new THREE.WebGLRenderer({
     canvas,
@@ -94,7 +99,7 @@ export function createHostRenderer(
     ...(opts?.alpha ? { alpha: true } : {}),
     ...(opts?.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
   });
-  renderer.setSize(width, height);
+  renderer.setSize(safeWidth, safeHeight);
   applyRendererSettings(renderer, rendering);
   renderer.shadowMap.type = THREE.PCFSoftShadowMap;
   renderer.toneMapping = toneMappingModes[DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
@@ -112,12 +117,14 @@ export function createSceneView(
   width = window.innerWidth,
   height = window.innerHeight,
 ): { scene: THREE.Scene; camera: THREE.PerspectiveCamera; composer: EffectComposer } {
+  const safeWidth = Math.max(1, width);
+  const safeHeight = Math.max(1, height);
   const scene = new THREE.Scene();
   scene.background = new THREE.Color(0x1a1a2e);
 
   const camera = new THREE.PerspectiveCamera(
     DEFAULTS.camera.fov,
-    width / height,
+    safeWidth / safeHeight,
     DEFAULTS.camera.near,
     DEFAULTS.camera.far,
   );