@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/runtime/types.ts

@@ -1,8 +1,10 @@
 import type RAPIER from '@dimforge/rapier3d-compat';
 import type { EffectComposer } from 'postprocessing';
 import type * as THREE from 'three';
+import type { z } from 'zod';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import type { AssetCache } from '../assets';
+import type { SeededRandom } from '../core/seeded-random';
 import type { createSystemRunner } from '../core/system-runner';
 import type { createDebugDraw } from '../dev/debug-draw';
 import type { ComponentManager } from '../ecs/component-manager';
@@ -13,7 +15,87 @@ import type { SceneFile } from '../scene/scene-types';
 import type { AudioContext as GameAudio } from '../setup/setup-audio';
 import type { ParticlesContext } from '../setup/setup-particles';
 import type { Game, WorldInstance } from './game';
-import type { SceneUIGameServices } from './scene-ui-bridge';
+
+/**
+ * The minimal structural shape `ctx.debug.attachRoom` needs from a joined
+ * Colyseus room (Task 2.2, `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1's "Multiplayer
+ * locus" note): just enough to send the reserved `__vgai:debugCommand`
+ * message and listen for its `__vgai:debugCommandResult` reply. Structural,
+ * not a Colyseus type import — the same seam-boundary style every other
+ * `DebugCtxSurface` member uses (no wrapper around Colyseus itself, D2).
+ * `onMessage`'s return type is `unknown` because Colyseus's own return shape
+ * (void in some client versions, an unsubscribe function in others) isn't
+ * load-bearing here: the registry calls it defensively (invokes it on detach
+ * only if it's actually a function).
+ */
+export interface DebugRoomHandle {
+  send(type: string, message?: unknown): void;
+  onMessage(type: string, cb: (message: unknown) => void): unknown;
+}
+
+/**
+ * Infers a `registerCommand`/`registerReactCommand`/`useDebugCommand`
+ * handler's parameter tuple from its declared Zod `args` tuple (dry-run
+ * finding, `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger —
+ * "`registerCommand` fn typing forces `unknown[]` casts"): a real
+ * `z.ZodTuple` infers its element types (`z.tuple([z.number(), z.string()])`
+ * → `(n: number, s: string) => ...`), while omitting `args` (the generic's
+ * `undefined` default) resolves to the original permissive
+ * `(...args: unknown[]) => ...` shape every command had before this generic
+ * existed. That permissive fallback is deliberate, not just a placeholder —
+ * it keeps every existing no-schema registration (including ones whose
+ * handler reads positional args the runtime never validates, since
+ * `invoke()` only parses `args` against a schema when one is declared)
+ * compiling byte-for-byte unchanged.
+ */
+export type DebugCommandArgs<T extends z.ZodTuple | undefined = undefined> = T extends z.ZodTuple
+  ? z.infer<T>
+  : unknown[];
+
+/**
+ * The authoring half of the debug/synthetic-player seam
+ * (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.1) — the read/actuate half is
+ * `SystemAdapters.DebugAdapter` (`adapter/system-adapter.ts`). Callable from
+ * any GameComponent's `init` (one file per new provider/command), or from a
+ * react world's `useDebugProvider`/`useDebugCommand`/`useDebugEmit` hooks. Every registration
+ * feeds the ONE game-scoped registry (`runtime/debug-registry.ts`) — never a
+ * per-world accumulator.
+ */
+export interface DebugCtxSurface {
+  /** Register (or replace) a named, JSON-serializable state read. Duplicate
+   *  names from the SAME world replace + warn once; the SAME name from a
+   *  DIFFERENT world throws (`DebugError` code `DEBUG_NAME_COLLISION`). */
+  registerStateProvider(
+    name: string,
+    fn: () => unknown,
+    opts?: { tier?: 'observable' | 'assisted' },
+  ): void;
+  /** Register (or replace) an invokable command. `locus` is REQUIRED once the
+   *  project declares a Colyseus room (`DebugRegistry.setRoomDeclared`) — a
+   *  fixture must say whether it mutates authoritative (server) or predicted
+   *  (client) state.
+   *
+   *  Generic over the declared `args` Zod tuple ({@link DebugCommandArgs}) so
+   *  `fn`'s parameters INFER from it: `registerCommand('setHp', { args:
+   *  z.tuple([z.number()]) }, (hp) => ...)` types `hp` as `number` with no
+   *  cast. Leaving `args` off keeps `fn` typed `(...args: unknown[]) => ...`,
+   *  same as before this generic existed. */
+  registerCommand<T extends z.ZodTuple | undefined = undefined>(
+    name: string,
+    spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+    fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+  ): void;
+  /** Push a tick-stamped event onto the debug event ring (spec §3.3) — the
+   *  engine stamps `tick`/`simT` at emission, not at read time. */
+  emit(event: string, detail?: unknown): void;
+  /**
+   * Task 2.2 — server-locus command routing (client leg). Call once your
+   * game code has joined its Colyseus room, so `locus: 'server'` commands
+   * have somewhere to send `__vgai:debugCommand`. Returns a detach function
+   * (call on room leave/dispose) — game-scoped, last-attached room wins.
+   */
+  attachRoom(room: DebugRoomHandle): () => void;
+}
 
 /**
  * All engine subsystems, passed to every game `setup(ctx)` and to each
@@ -84,21 +166,17 @@ export interface GameContext {
   /** Manager for all live GameComponent instances (attach/detach/HMR). The
    *  scene loader drives this; gameplay code rarely touches it directly. */
   components: ComponentManager;
-  /** DOM element overlaying the canvas for game UI (React via `mountUI`, or
-   *  vanilla). `pointer-events:none` by default — set `auto` on interactive
-   *  elements. Cleared on scene switch / hot-reload. */
-  uiContainer: HTMLDivElement;
   /** Register a game-owned `SystemAdapters` capability (networking,
    *  navigation, …) on the mounted game's adapter surface, so the editor's
    *  introspection panels (via `getActiveSystems()`) can see it. The engine
-   *  wires the first-party physics/input/assets/animation entries itself;
+   *  wires the first-party physics/input/assets/audio entries itself;
    *  capabilities the GAME owns (a Colyseus connection, a NavMeshManager)
    *  are registered here by the game's setup. Optional capability — absent
    *  in contexts that expose no adapter surface (some test harnesses);
    *  call as `ctx.registerSystemAdapter?.(…)`.
    *
    *  Ordering contract: **game registrations always win** — the engine seeds
-   *  its first-party entries (physics/input/assets/animation) BEFORE setup()
+   *  its first-party entries (physics/input/assets/audio) BEFORE setup()
    *  runs, so a game that registers any of those same kinds during its own
    *  setup overrides the engine's entry, not the other way around. This also
    *  holds across a warm restart (`hotReload`): every kind the outgoing game
@@ -108,27 +186,31 @@ export interface GameContext {
    *  mounted surface. */
   registerSystemAdapter?<K extends keyof SystemAdapters>(kind: K, adapter: SystemAdapters[K]): void;
 
+  /** The debug/synthetic-player authoring surface (`docs/SYNTHETIC-PLAYER-SPEC.md`
+   *  §3.1) — see {@link DebugCtxSurface}. Optional, same absence precedent as
+   *  `registerSystemAdapter`: present on every first-party mount, absent only
+   *  in bare test harnesses that build a hand-rolled `ctx`. */
+  debug?: DebugCtxSurface;
+
   /**
-   * Register (or replace) this game's scene-UI game-time services — the data
-   * source, custom onEvent handler, and/or worldProjector overrides a scene's
-   * authored UI mounts against (design/24-scene-ui.md D2/D7). Optional, same
-   * precedent as `registerSystemAdapter`: absent in contexts with no scene-UI
-   * surface at all (bare test harnesses).
-   *
-   * Timing is safe by construction: the scene loader awaits
-   * `componentManager.initAll()` before `loadScene`/`loadSceneFromData`
-   * return, and the adapter mounts scene UI only after that — so calling this
-   * from a `GameComponent.init()` always beats the mount (its services are
-   * folded into the FIRST render, not a late update). A call AFTER the mount
-   * (e.g. from a click handler) updates the live mount in place instead
-   * (`SceneUIHandle.update`, or a dispose+remount if the renderer has none).
-   *
-   * Per-key merge (D2): a key set here always wins over both the project's
-   * registration-time registry and the engine's own D4/D5/D6 defaults. Hot
-   * reload strips every game-registered key back to none before the incoming
-   * game's `init()` runs — same contract as `registerSystemAdapter`'s re-seed.
+   * D15 (T-D15.1, `docs/D15-DETERMINISM-DESIGN.md` §2.a) — the game-scoped,
+   * named-stream seeded PRNG. `ctx.random()` draws from the `'gameplay'`
+   * stream; `ctx.random.stream('vfx')` (or any other name) draws from an
+   * INDEPENDENT stream, so a cosmetic/VFX draw can never shift the gameplay
+   * draw sequence. Use this instead of raw `Math.random()` for anything a
+   * project wants to keep reproducible; `ctx.random` itself always exists
+   * and is always internally consistent (same seed ⇒ same sequence) whether
+   * or not the project's manifest declares `determinism.seededRandom` — that
+   * flag only gates the BOOT-TIME seeding from
+   * `manifest.determinism.defaultSeed`/`?vgai-seed=`, the burn-down lint
+   * scan, and the dev-mode `Math.random` phase trap (three separate
+   * enforcers, `test/gameplay-rng-ban.test.ts` + `runtime/gameplay-rng-trap.ts`),
+   * never `ctx.random`'s mere presence. Same absence precedent as `debug`
+   * above: present on every first-party mount, optional only for bare test
+   * harnesses that build a hand-rolled `ctx`. `reseed(seed)` (future draws
+   * only) is `play.seed.set`'s eventual target (T-D15.6, not yet wired).
    */
-  setSceneUIServices?(services: SceneUIGameServices): void;
+  random?: SeededRandom;
 
   // ─── Game root (T7.1 slice 1 — GAME-ROOT-DESIGN.md D6) ───
 
@@ -138,9 +220,9 @@ export interface GameContext {
    *  harness that builds a hand-rolled `ctx` object keeps compiling
    *  unmodified — the same precedent as `registerSystemAdapter`. */
   game?: Game | undefined;
-  /** Alias for `game.worlds` — the live, declaration-ordered world registry.
+  /** Alias for `game.roots` — the live, declaration-ordered world registry.
    *  Same optionality/absence rule as `game` above. */
-  worlds?: ReadonlyArray<WorldInstance> | undefined;
+  roots?: ReadonlyArray<WorldInstance> | undefined;
 }
 
 /** Return value from a game setup function. */

package/src/scene/asset-registry.ts

@@ -5,6 +5,7 @@
  * and editor entity factory import from this module.
  */
 
+import * as THREE from 'three';
 import { resolveUrl } from '../loader';
 
 export interface ImportCorrection {
@@ -18,6 +19,27 @@ export interface AssetMeta {
   importCorrection?: ImportCorrection;
 }
 
+/**
+ * Apply an asset's visual-only import correction to the loaded GLTF content.
+ * Call this on the model child, before placing it under the entity wrapper, so
+ * gameplay transforms, physics, cameras, and movement remain in VGAI's Y-up /
+ * -Z-forward coordinate contract.
+ */
+export function applyImportCorrection(
+  content: THREE.Object3D,
+  correction: ImportCorrection | undefined,
+): void {
+  if (!correction) return;
+  if (correction.scale !== undefined) content.scale.multiplyScalar(correction.scale);
+  if (correction.rotation) {
+    content.rotation.set(
+      THREE.MathUtils.degToRad(correction.rotation[0]),
+      THREE.MathUtils.degToRad(correction.rotation[1]),
+      THREE.MathUtils.degToRad(correction.rotation[2]),
+    );
+  }
+}
+
 type AssetRegistry = Record<string, AssetMeta>;
 
 let registryCache: AssetRegistry | null = null;

package/src/scene/component-registry.ts

@@ -1,13 +1,24 @@
 import type * as THREE from 'three';
 import type { ComponentManager } from '../ecs/component-manager';
-import { GameComponent, type GameComponentClass } from '../ecs/game-component';
+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? */
+/** 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 {
-  return typeof entry === 'function' && entry.prototype instanceof GameComponent;
+  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;
 }
 
 /**

package/src/scene/defaults.ts

@@ -40,6 +40,7 @@ export const DEFAULTS = {
     intensity: 1,
     groundColor: '#000000',
     distance: 0,
+    decay: 2,
     angle: Math.PI / 6,
     penumbra: 0,
     // three.js's own RectAreaLight constructor defaults (area lights only).

package/src/scene/light-camera-factory.ts

@@ -42,15 +42,23 @@ export function createLight(def: SceneLight): THREE.Light {
     case 'directional':
       return new THREE.DirectionalLight(color, intensity);
     case 'point':
-      return new THREE.PointLight(color, intensity, def.distance ?? d.distance);
-    case 'spot':
-      return new THREE.SpotLight(
+      return new THREE.PointLight(
+        color,
+        intensity,
+        def.distance ?? d.distance,
+        def.decay ?? d.decay,
+      );
+    case 'spot': {
+      const light = new THREE.SpotLight(
         color,
         intensity,
         def.distance ?? d.distance,
         def.angle ?? d.angle,
         def.penumbra ?? d.penumbra,
       );
+      light.decay = def.decay ?? d.decay;
+      return light;
+    }
     case 'hemisphere':
       return new THREE.HemisphereLight(color, def.groundColor ?? d.groundColor, intensity);
     case 'area': {

package/src/scene/scene-apply.ts

@@ -114,6 +114,49 @@ function cloneEntity(e: SceneEntity): SceneEntity {
   return JSON.parse(JSON.stringify(e)) as SceneEntity;
 }
 
+/** True iff at least one entity in the tree (at any depth) carries a persisted `id`. */
+function hasAnyPersistedId(entities: SceneEntity[]): boolean {
+  for (const e of entities) {
+    if (e.id) return true;
+    if (e.children && hasAnyPersistedId(e.children)) return true;
+  }
+  return false;
+}
+
+/**
+ * The id-persistence trap, made honest.
+ *
+ * `id` is `z.string().optional()` in the entity schema ("auto-generated if
+ * omitted"), and the ids an agent can actually DISCOVER — `vgai status`' —
+ * are the RUNTIME uuids a live editor session assigns to id-less entities on
+ * load (`editor-store.ts`'s `assignMissingIds`). `applyDiff` resolves ops
+ * against the FILE. So for any scene authored the normal way (hand-written,
+ * or scaffolded — none of which shipped with ids), the only ids on offer
+ * could never resolve here, and the failure read `entity not found` — as if
+ * the CALLER had typo'd the id. It is not a typo: NOTHING in that file could
+ * ever have matched.
+ *
+ * The durable half of the fix makes ids real (the editor now persists
+ * auto-assigned ids back to the scene file on load — see `loadDocument`), so
+ * this message is the safety net for a file that has not been through that
+ * path yet. It fires ONLY when the scene has zero persisted ids at all — a
+ * genuine bad-id typo against an id-carrying scene still gets the plain,
+ * unpadded message.
+ */
+const NO_IDS_HINT =
+  ' — and this scene file has NO persisted entity ids AT ALL, so nothing in it could have ' +
+  'matched, whatever id the op named. This is almost certainly not a typo: `vgai status` ' +
+  'reports RUNTIME ids a live editor session assigns to id-less entities on load, and those ' +
+  'only exist in the FILE once the editor has written them back (it now does that ' +
+  'automatically, via autosave, shortly after the scene loads). Open this scene in the editor ' +
+  '(`vgai edit`), let it autosave, then re-read the ids with `vgai status` and retry. Do not ' +
+  'hand-write ids into the file.';
+
+/** Append the no-ids explanation to a not-found message when (and only when) the file has no ids. */
+function notFound(message: string, sceneHasIds: boolean): string {
+  return sceneHasIds ? message : message + NO_IDS_HINT;
+}
+
 /** Recursively search `list` (and descendants) for `id`; if found, splice it out (subtree intact) and return it. */
 function detachById(list: SceneEntity[], id: string): SceneEntity | undefined {
   for (let i = 0; i < list.length; i++) {
@@ -168,6 +211,9 @@ interface Placement {
 export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
   const working: SceneFile = JSON.parse(JSON.stringify(scene)) as SceneFile;
   const ops = diff.ops;
+  // Captured from the INPUT scene, before any op mutates `working` — see
+  // `NO_IDS_HINT` above for what this distinguishes and why.
+  const sceneHasIds = hasAnyPersistedId(scene.entities);
 
   // --- Metadata / environment (independent of entity ops) ---
   if (diff.metaChanged && diff.newName !== undefined) {
@@ -227,7 +273,12 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
   if (pendingMoves.size > 0) {
     const i = [...pendingMoves][0]!;
     const op = ops[i] as Extract<DiffOp, { type: 'move' }>;
-    throw new ApplyDiffError('entity not found (nothing to move)', i, 'move', op.id);
+    throw new ApplyDiffError(
+      notFound('entity not found (nothing to move)', sceneHasIds),
+      i,
+      'move',
+      op.id,
+    );
   }
 
   // --- Phase 2: removes (a not-found target is fine if it was already swept
@@ -243,7 +294,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
     }
     if (sweptIds.has(op.id)) return;
     throw new ApplyDiffError(
-      'entity not found (already removed via an ancestor, or an invalid id)',
+      notFound('entity not found (already removed via an ancestor, or an invalid id)', sceneHasIds),
       i,
       'remove',
       op.id,
@@ -311,7 +362,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
       if (!parentNode) {
         const bad = placements[0]!;
         throw new ApplyDiffError(
-          `parent entity "${parentId}" not found`,
+          notFound(`parent entity "${parentId}" not found`, sceneHasIds),
           bad.opIndex,
           bad.opType,
           bad.entityId,
@@ -341,7 +392,7 @@ export function applyDiff(scene: SceneFile, diff: SceneDiff): SceneFile {
     if (op.type !== 'update') return;
     const node = byId.get(op.id);
     if (!node) {
-      throw new ApplyDiffError('entity not found', i, 'update', op.id);
+      throw new ApplyDiffError(notFound('entity not found', sceneHasIds), i, 'update', op.id);
     }
     const { id: _id, children: _children, ...fields } = op.entity;
     for (const key of Object.keys(node) as (keyof SceneEntity)[]) {

package/src/scene/scene-loader.ts

@@ -16,7 +16,7 @@ import {
   loadGLTF,
   resolveGltfNode,
 } from './asset-loaders';
-import { getAssetMeta, loadRegistry } from './asset-registry';
+import { applyImportCorrection, getAssetMeta, loadRegistry } from './asset-registry';
 import { computeColliderWorldDimensions, computeColliderWorldOffset } from './collider-dimensions';
 import { applyComponents, type ComponentRegistry } from './component-registry';
 import { DEFAULTS } from './defaults';
@@ -39,7 +39,6 @@ import {
   type SceneMaterial,
   type ScenePhysics,
   type SceneSpline,
-  type UIRoot,
 } from './scene-types';
 import { isEntityRefSchema } from './schema/entity-ref';
 import { getUserData, setUserData } from './user-data';
@@ -213,16 +212,6 @@ export interface SceneInstance {
   /** Parsed scene environment, if any — lets the runtime apply post-processing
    *  (which needs the composer/camera the loader doesn't have). */
   environment?: SceneEnvironment | undefined;
-  /**
-   * The scene file's top-level `ui` tree (React UI roots/canvases, A1),
-   * carried through verbatim from the parsed `SceneFile` by BOTH `loadScene`
-   * and `loadSceneFromData` (single source of truth — R8 item 7 / B). Opaque
-   * to the loader itself; the adapter passes it to `renderSceneUI` (the
-   * injected React renderer) so scenePath and sceneData mounts render the
-   * SAME scene-authored UI instead of only the sceneData branch special-
-   * casing it. `undefined` when the scene file has no `ui` field.
-   */
-  ui?: UIRoot[] | undefined;
   /**
    * Authored entity id -> spawned Object3D (design/24-scene-ui.md D5). The
    * SAME map `spawnEntity`/`createSceneJoints` build internally (id-less
@@ -526,7 +515,6 @@ async function instantiateScene(
     navMesh,
     cameras,
     environment: data.environment,
-    ui: data.ui,
     entities: idMap,
     update(dt: number) {
       for (const fn of tickFns) fn(dt);
@@ -674,20 +662,7 @@ async function spawnEntity(
       }
 
       // Apply import correction from asset registry
-      const meta = getAssetMeta(def.mesh.src);
-      if (meta?.importCorrection) {
-        const ic = meta.importCorrection;
-        if (ic.scale !== undefined) {
-          content.scale.multiplyScalar(ic.scale);
-        }
-        if (ic.rotation) {
-          content.rotation.set(
-            THREE.MathUtils.degToRad(ic.rotation[0]),
-            THREE.MathUtils.degToRad(ic.rotation[1]),
-            THREE.MathUtils.degToRad(ic.rotation[2]),
-          );
-        }
-      }
+      applyImportCorrection(content, getAssetMeta(def.mesh.src)?.importCorrection);
 
       // Wrap in a group so entity transform and import correction are separated.
       // `content` carries import correction; wrapper carries entity transform.
@@ -1098,6 +1073,14 @@ function createPhysicsBody(
   }
   if (col.isSensor) {
     colliderDesc.setSensor(true);
+    // Rapier's DEFAULT omits every non-dynamic pair. Player characters are
+    // commonly position-based kinematic bodies and authored pickups commonly
+    // use fixed sensors, so DEFAULT makes the pair invisible to the physics
+    // event queue even after the KCC correctly excludes sensors from movement
+    // blocking. A sensor's contract is observation, not contact response:
+    // enable every body-type pair so real overlaps consistently reach
+    // onTriggerEnter/Exit.
+    colliderDesc.setActiveCollisionTypes(rapier.ActiveCollisionTypes.ALL);
   }
   // All scene-loaded colliders opt into collision events — sensors need them for
   // onTriggerEnter/onTriggerExit, and solid colliders need them for onCollision

package/src/scene/scene-types.ts

@@ -28,7 +28,6 @@ export type {
   ScenePostProcessing,
   SceneSpline,
   SceneToneMapping,
-  UIRoot,
 } from './schema';
 
 export { mergePrefabInstance } from './schema';

package/src/scene/schema/index.ts

@@ -49,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