@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

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';
@@ -59,37 +49,3 @@ export { SceneSplineOverrideSchema, SceneSplineSchema } from './spline';
 // Inferred types
 export type { Quat, SceneTransform, Vec3 } from './tuples';
 export { QuatSchema, TransformSchema, Vec3Schema } from './tuples';
-// UI scene-graph schema (editable React UI in the scene graph)
-export type {
-  UIAnimatableProperty,
-  UIAnimation,
-  UIBinding,
-  UIEasing,
-  UIKeyframe,
-  UILayout,
-  UINode,
-  UINodeKind,
-  UIPrefabFile,
-  UIRoot,
-  UIStyle,
-  UITheme,
-  UIThemeFile,
-  UITrack,
-} from './ui';
-export {
-  UIAnimatablePropertySchema,
-  UIAnimationSchema,
-  UIBindingSchema,
-  UIEasingSchema,
-  UIKeyframeSchema,
-  UILayoutSchema,
-  UINodeKindSchema,
-  UINodeSchema,
-  UIPrefabFileSchema,
-  UIRootSchema,
-  UIStateStylesSchema,
-  UIStyleSchema,
-  UIThemeFileSchema,
-  UIThemeSchema,
-  UITrackSchema,
-} from './ui';

package/src/scene/schema/light.ts

@@ -3,12 +3,27 @@ import { z } from 'zod';
 const SceneLightBase = z.object({
   type: z.enum(['directional', 'point', 'spot', 'hemisphere', 'area']).describe('Light type'),
   color: z.string().optional().describe('Light color as CSS hex string'),
-  intensity: z.number().optional().describe('Light intensity multiplier'),
+  intensity: z
+    .number()
+    .optional()
+    .describe(
+      'Native Three.js light intensity. Point and spot lights use candela with inverse-square ' +
+        'falloff (a value near 1 is candle-scale); area lights use nit; directional and ' +
+        'hemisphere lights use Three.js scene-light intensity units.',
+    ),
   groundColor: z.string().optional().describe('Ground color for hemisphere lights'),
   distance: z
     .number()
     .optional()
     .describe('Maximum range of the light. 0 = infinite (point/spot only)'),
+  decay: z
+    .number()
+    .nonnegative()
+    .optional()
+    .describe(
+      'Native Three.js distance-decay exponent for point/spot lights. Default 2 gives ' +
+        'physically correct inverse-square falloff.',
+    ),
   angle: z.number().optional().describe('Spotlight cone angle in radians (spot only)'),
   penumbra: z.number().optional().describe('Spotlight penumbra softness 0–1 (spot only)'),
   width: z

package/src/scene/schema/material.ts

@@ -1,103 +1,108 @@
 import { z } from 'zod';
 
-export const SceneMaterialSchema = z
-  .object({
-    type: z
-      .enum(['standard', 'physical', 'basic', 'toon', 'custom'])
-      .describe('Material shading model. "custom" resolves `def` against the material registry'),
-    def: z
-      .string()
-      .optional()
-      .describe('Registered custom-material name (required when type is "custom")'),
-    uniforms: z
-      .record(z.string(), z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]))
-      .optional()
-      .describe('Authored uniform values for a custom material, keyed by uniform name'),
-    color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
-    metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
-    roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
-    map: z.string().optional().describe('Path to albedo/diffuse texture image'),
-    normalMap: z.string().optional().describe('Path to normal map texture image'),
-    emissive: z.string().optional().describe('Emissive color as CSS hex string'),
-    emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
-    emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
-    aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
-    lightMap: z
-      .string()
-      .optional()
-      .describe(
-        "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
-      ),
-    lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
-    roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
-    metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
-    opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
-    transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
-    side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
-    flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
+const SceneMaterialObjectSchema = z.object({
+  type: z
+    .enum(['standard', 'physical', 'basic', 'toon', 'custom'])
+    .describe('Material shading model. "custom" resolves `def` against the material registry'),
+  def: z
+    .string()
+    .optional()
+    .describe('Registered custom-material name (required when type is "custom")'),
+  uniforms: z
+    .record(z.string(), z.union([z.number(), z.string(), z.boolean(), z.array(z.number())]))
+    .optional()
+    .describe('Authored uniform values for a custom material, keyed by uniform name'),
+  color: z.string().optional().describe('Base color as CSS hex string (e.g. "#ff0000")'),
+  metalness: z.number().optional().describe('Metalness factor 0–1 (standard/physical only)'),
+  roughness: z.number().optional().describe('Roughness factor 0–1 (standard/physical only)'),
+  map: z.string().optional().describe('Path to albedo/diffuse texture image'),
+  normalMap: z.string().optional().describe('Path to normal map texture image'),
+  emissive: z.string().optional().describe('Emissive color as CSS hex string'),
+  emissiveIntensity: z.number().optional().describe('Emissive light intensity multiplier'),
+  emissiveMap: z.string().optional().describe('Path to emissive map texture image'),
+  aoMap: z.string().optional().describe('Path to ambient occlusion map texture image'),
+  lightMap: z
+    .string()
+    .optional()
+    .describe(
+      "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
+    ),
+  lightMapIntensity: z.number().optional().describe('Lightmap intensity multiplier (default 1).'),
+  roughnessMap: z.string().optional().describe('Path to roughness map texture image'),
+  metalnessMap: z.string().optional().describe('Path to metalness map texture image'),
+  opacity: z.number().optional().describe('Opacity 0–1. Set transparent: true to enable'),
+  transparent: z.boolean().optional().describe('Enable alpha blending for this material'),
+  side: z.enum(['front', 'back', 'double']).optional().describe('Which face sides to render'),
+  flatShading: z.boolean().optional().describe('Use flat (faceted) shading instead of smooth'),
 
-    // Physical material feature groups (physical only, all optional)
-    clearcoat: z
-      .object({
-        clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
-        clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
-        clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
-        clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
-      })
-      .optional()
-      .describe('Clearcoat layer (physical only)'),
+  // Physical material feature groups (physical only, all optional)
+  clearcoat: z
+    .object({
+      clearcoat: z.number().describe('Clearcoat layer intensity 0–1'),
+      clearcoatRoughness: z.number().optional().describe('Clearcoat roughness 0–1'),
+      clearcoatMap: z.string().optional().describe('Path to clearcoat intensity map'),
+      clearcoatRoughnessMap: z.string().optional().describe('Path to clearcoat roughness map'),
+    })
+    .optional()
+    .describe('Clearcoat layer (physical only)'),
 
-    transmission: z
-      .object({
-        transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
-        ior: z.number().optional().describe('Index of refraction (default 1.5)'),
-        thickness: z.number().optional().describe('Volume thickness for refraction'),
-        attenuationColor: z.string().optional().describe('Color absorbed over distance'),
-        attenuationDistance: z
-          .number()
-          .optional()
-          .describe('Distance at which attenuation color takes full effect'),
-        transmissionMap: z.string().optional().describe('Path to transmission map'),
-      })
-      .optional()
-      .describe('Light transmission (physical only)'),
+  transmission: z
+    .object({
+      transmission: z.number().describe('Transmission intensity 0–1 (glass, liquid)'),
+      ior: z.number().optional().describe('Index of refraction (default 1.5)'),
+      thickness: z.number().optional().describe('Volume thickness for refraction'),
+      attenuationColor: z.string().optional().describe('Color absorbed over distance'),
+      attenuationDistance: z
+        .number()
+        .optional()
+        .describe('Distance at which attenuation color takes full effect'),
+      transmissionMap: z.string().optional().describe('Path to transmission map'),
+    })
+    .optional()
+    .describe('Light transmission (physical only)'),
 
-    sheen: z
-      .object({
-        sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
-        sheenColor: z.string().optional().describe('Sheen tint color'),
-        sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
-        sheenColorMap: z.string().optional().describe('Path to sheen color map'),
-        sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
-      })
-      .optional()
-      .describe('Sheen layer (physical only)'),
+  sheen: z
+    .object({
+      sheen: z.number().describe('Sheen intensity 0–1 (fabric, velvet)'),
+      sheenColor: z.string().optional().describe('Sheen tint color'),
+      sheenRoughness: z.number().optional().describe('Sheen roughness 0–1'),
+      sheenColorMap: z.string().optional().describe('Path to sheen color map'),
+      sheenRoughnessMap: z.string().optional().describe('Path to sheen roughness map'),
+    })
+    .optional()
+    .describe('Sheen layer (physical only)'),
 
-    iridescence: z
-      .object({
-        iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
-        iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
-        iridescenceThicknessRange: z
-          .tuple([z.number(), z.number()])
-          .optional()
-          .describe('Min/max thin-film thickness in nm'),
-        iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
-        iridescenceThicknessMap: z
-          .string()
-          .optional()
-          .describe('Path to iridescence thickness map'),
-      })
-      .optional()
-      .describe('Iridescence thin-film (physical only)'),
+  iridescence: z
+    .object({
+      iridescence: z.number().describe('Iridescence intensity 0–1 (soap bubbles, oil slick)'),
+      iridescenceIOR: z.number().optional().describe('Thin-film IOR (default 1.3)'),
+      iridescenceThicknessRange: z
+        .tuple([z.number(), z.number()])
+        .optional()
+        .describe('Min/max thin-film thickness in nm'),
+      iridescenceMap: z.string().optional().describe('Path to iridescence intensity map'),
+      iridescenceThicknessMap: z.string().optional().describe('Path to iridescence thickness map'),
+    })
+    .optional()
+    .describe('Iridescence thin-film (physical only)'),
 
-    displacementMap: z.string().optional().describe('Path to displacement/height map'),
-    displacementScale: z.number().optional().describe('Displacement height multiplier'),
-    displacementBias: z.number().optional().describe('Displacement offset'),
-  })
-  .describe('Material appearance properties');
+  displacementMap: z.string().optional().describe('Path to displacement/height map'),
+  displacementScale: z.number().optional().describe('Displacement height multiplier'),
+  displacementBias: z.number().optional().describe('Displacement offset'),
+});
+
+export const SceneMaterialSchema = SceneMaterialObjectSchema.superRefine((material, ctx) => {
+  if (material.type === 'custom' && !material.def?.trim()) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['def'],
+      message: 'Custom material requires a non-empty registered definition name',
+    });
+  }
+}).describe('Material appearance properties');
 
 /** Partial schema for prefab instance overrides (type not required). */
-export const SceneMaterialOverrideSchema = SceneMaterialSchema.partial();
+export const SceneMaterialOverrideSchema = SceneMaterialObjectSchema.partial();
 
 export type SceneMaterial = z.infer<typeof SceneMaterialSchema>;
 

package/src/scene/schema/scene-file.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import { type SceneEntity, SceneEntitySchema } from './entity';
 import { SceneEnvironmentSchema } from './environment';
-import { UIRootSchema } from './ui';
 
 export const SceneFileSchema = z
   .object({
@@ -9,13 +8,8 @@ export const SceneFileSchema = z
     name: z.string().describe('Scene display name'),
     environment: SceneEnvironmentSchema.optional().describe('Scene-level environment settings'),
     entities: z.array(SceneEntitySchema).describe('Top-level entities in the scene'),
-    // UI roots (HUD/menus) attached to the scene graph as data. Optional and
-    // additive — pre-UI scenes (no `ui` field) load unchanged (A4 versioning).
-    ui: z
-      .array(UIRootSchema)
-      .optional()
-      .describe('React UI roots (canvases) attached to the scene graph (A1)'),
   })
+  .strict()
   .describe('Scene file (.vscn.json)');
 
 export type SceneFile = z.infer<typeof SceneFileSchema>;

package/src/scene/user-data.ts

@@ -36,9 +36,14 @@
  *
  * 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).
+ * - `_xstateAnimation`    — live native XState/Three binding exposed for
+ *                           play-mode inspection; removed when binding disposes.
  *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
@@ -74,6 +79,8 @@
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
  * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `skeletonVisible`     — per-entity editor preference for its bone overlay.
+ * - `skeletonEnabled`     — resolved visibility preference on a skeleton helper.
  * - `envObject`           — `true` for environment objects (ambient light, etc.).
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
@@ -81,8 +88,8 @@
 
 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 { AnyActor } from 'xstate';
+import type { XStateAnimationBinding } from '../animation/xstate-animation-binding';
 import type { SceneEntity } from './scene-types';
 
 /** The kinds of editor helper objects tagged via `editorHelperType`. */
@@ -94,7 +101,8 @@ export type EditorHelperType =
   | 'splines'
   | 'particles'
   | 'pivot'
-  | 'navmesh';
+  | 'navmesh'
+  | 'skeletons';
 
 /**
  * Maps each canonical accessor name to its value type. This is the single
@@ -112,9 +120,9 @@ export interface UserDataSchema {
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
   _animMixer: THREE.AnimationMixer;
-  _animGraph: AnimGraph;
-  _animGraphData: AnimGraphFile;
+  _animClips: Map<string, THREE.AnimationClip>;
   _availableClips: string[];
+  _xstateAnimation: XStateAnimationBinding & { readonly actor: AnyActor };
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -128,6 +136,8 @@ export interface UserDataSchema {
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
+  skeletonVisible: boolean;
+  skeletonEnabled: boolean;
   envObject: boolean;
   vcDirIdx: number;
 }
@@ -152,9 +162,9 @@ export const UserDataKeys = {
   _camera: '_camera',
   _particleSystem: '_particleSystem',
   _animMixer: '_animMixer',
-  _animGraph: '_animGraph',
-  _animGraphData: '_animGraphData',
+  _animClips: '_animClips',
   _availableClips: '_availableClips',
+  _xstateAnimation: '_xstateAnimation',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',
@@ -168,6 +178,8 @@ export const UserDataKeys = {
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',
+  skeletonVisible: 'skeletonVisible',
+  skeletonEnabled: 'skeletonEnabled',
   envObject: 'envObject',
   vcDirIdx: 'vcDirIdx',
 } as const satisfies Record<UserDataKey, string>;

package/src/setup/setup-renderer.ts

@@ -74,7 +74,7 @@ export function applyRendererSettings(
  * `opts` is additive (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §1/§4): omitted
  * entirely, construction is byte-identical to before (no `alpha`/
  * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
- * passes it. The worlds path passes `alpha:true` for every stacked canvas
+ * passes it. The roots path passes `alpha:true` for every stacked canvas
  * above the bottom one (so its clear-alpha-0 shows the layer below through
  * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
  * recorded capture-tier cost, paid once here rather than re-derived later).
@@ -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,
   );