@vgai/engine 0.2.0

package/src/scene/collider-dimensions.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared world-scale collider dimension math (T1.2).
+ *
+ * Rapier colliders have no notion of a parent Object3D's `scale` — a body's
+ * shape is defined in absolute world units at creation time. Three.js meshes,
+ * by contrast, scale visually for free via the normal Object3D hierarchy. To
+ * keep the physical collider matching what's on screen, the LOADER must bake
+ * the entity's composed WORLD scale (self × every transformed ancestor — see
+ * T1.1's world-transform composition) into the collider's dimensions at
+ * creation time.
+ *
+ * This is the ONE place that does that math, so both the runtime loader
+ * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
+ * (gizmo-registry.ts) agree on exactly the same numbers — previously the
+ * editor gizmo only rendered the entity's own live Object3D scale (via normal
+ * Three.js parenting) while the Rapier body ignored scale entirely, so the
+ * two silently agreed by coincidence for uniform scale and disagreed for
+ * everything else.
+ *
+ * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
+ * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
+ * round collider's round axes throws a loud error naming the entity, rather
+ * than silently simulating (or rendering) the wrong shape.
+ */
+
+import { DEFAULTS } from './defaults';
+import type { SceneCollider } from './scene-types';
+
+/** Axes are considered "uniform enough" within this tolerance (float error only). */
+const UNIFORM_SCALE_EPSILON = 1e-4;
+
+export interface ColliderWorldDimensions {
+  /** cuboid only: per-axis half-extents, world scale applied. */
+  halfExtents?: [number, number, number];
+  /** ball/capsule only: radius, world scale applied (uniform axes required). */
+  radius?: number;
+  /** capsule only: half-height along the capsule's axis, world scale applied. */
+  halfHeight?: number;
+}
+
+/**
+ * Compute a collider's WORLD-space dimensions given the entity's composed
+ * world scale (self × ancestors, per-axis, in the entity's own local frame —
+ * X/Y/Z order matches `SceneEntity.transform.scale`).
+ *
+ * @param collider - the entity's authored (unscaled) collider definition.
+ * @param worldScale - composed world scale `[x, y, z]`.
+ * @param entityLabel - human-readable entity identifier, used only in thrown
+ *   error messages (loud-failure naming, never silently wrong).
+ * @throws if a ball/capsule collider's round cross-section axes have a
+ *   non-uniform world scale (beyond {@link UNIFORM_SCALE_EPSILON}).
+ */
+export function computeColliderWorldDimensions(
+  collider: SceneCollider,
+  worldScale: readonly [number, number, number],
+  entityLabel: string,
+): ColliderWorldDimensions {
+  const [sx, sy, sz] = worldScale;
+
+  switch (collider.type) {
+    case 'cuboid': {
+      const he = collider.halfExtents ?? DEFAULTS.collider.cuboid.halfExtents;
+      return { halfExtents: [he[0]! * sx, he[1]! * sy, he[2]! * sz] };
+    }
+    case 'ball': {
+      if (
+        Math.abs(sx - sy) > UNIFORM_SCALE_EPSILON ||
+        Math.abs(sy - sz) > UNIFORM_SCALE_EPSILON ||
+        Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON
+      ) {
+        throw new Error(
+          `Entity "${entityLabel}" has a "ball" collider under a non-uniform world scale ` +
+            `[${sx}, ${sy}, ${sz}]. Rapier ball colliders are always perfect spheres — a ` +
+            `non-uniform scale cannot be represented and would silently simulate the wrong ` +
+            `shape. Use a uniform scale on this entity (and every transformed ancestor), or ` +
+            `switch to a "cuboid" collider.`,
+        );
+      }
+      const radius = collider.radius ?? DEFAULTS.collider.ball.radius;
+      return { radius: radius * sx };
+    }
+    case 'capsule': {
+      // Rapier capsules run their half-height along the local Y axis, with a
+      // circular cross-section in the XZ plane — so only X/Z need to match.
+      if (Math.abs(sx - sz) > UNIFORM_SCALE_EPSILON) {
+        throw new Error(
+          `Entity "${entityLabel}" has a "capsule" collider whose X/Z world scale differs ` +
+            `(x=${sx}, z=${sz}). Rapier capsule colliders have a circular cross-section — a ` +
+            `non-uniform X/Z scale cannot be represented and would silently simulate the ` +
+            `wrong shape. Use a uniform X/Z scale on this entity (and every transformed ` +
+            `ancestor), or switch to a "cuboid" collider.`,
+        );
+      }
+      const radius = collider.radius ?? DEFAULTS.collider.capsule.radius;
+      const halfHeight = collider.halfHeight ?? DEFAULTS.collider.capsule.halfHeight;
+      return { radius: radius * sx, halfHeight: halfHeight * sy };
+    }
+    default:
+      return {};
+  }
+}
+
+/**
+ * Compute a collider's WORLD-scaled translation offset (sibling to
+ * {@link computeColliderWorldDimensions}, same input contract).
+ *
+ * Rapier's `ColliderDesc.setTranslation` is a raw physics-engine offset with no
+ * notion of a parent Object3D's scale — like dimensions, an authored `offset`
+ * (in the entity's own local units) must be scaled per-axis by the entity's
+ * composed world scale before being handed to Rapier, or the collider's center
+ * silently drifts away from its visual anchor point under any non-1 scale.
+ * Applies to every collider type (including trimesh, which is otherwise not
+ * handled by {@link computeColliderWorldDimensions}).
+ *
+ * Returns `undefined` when no offset is authored, mirroring the `if (col.offset)`
+ * guard call sites already use.
+ */
+export function computeColliderWorldOffset(
+  offset: readonly [number, number, number] | undefined,
+  worldScale: readonly [number, number, number],
+): [number, number, number] | undefined {
+  if (!offset) return undefined;
+  const [sx, sy, sz] = worldScale;
+  return [offset[0] * sx, offset[1] * sy, offset[2] * sz];
+}

package/src/scene/component-registry.ts

@@ -0,0 +1,40 @@
+import type * as THREE from 'three';
+import type { ComponentManager } from '../ecs/component-manager';
+import { 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? */
+export function isGameComponentClass(entry: unknown): entry is GameComponentClass {
+  return typeof entry === 'function' && entry.prototype instanceof GameComponent;
+}
+
+/**
+ * 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/defaults.ts

@@ -0,0 +1,164 @@
+/** Single source of truth for all scene default values. */
+export const DEFAULTS = {
+  transform: {
+    position: [0, 0, 0] as [number, number, number],
+    rotation: [0, 0, 0, 1] as [number, number, number, number],
+    scale: [1, 1, 1] as [number, number, number],
+  },
+
+  entity: {
+    visible: true,
+    locked: false,
+    pivot: [0, 0, 0] as [number, number, number],
+  },
+
+  material: {
+    type: 'standard' as const,
+    color: '#888888',
+    metalness: 0,
+    roughness: 0.5,
+    emissive: '#000000',
+    emissiveIntensity: 0,
+    opacity: 1,
+    transparent: false,
+    side: 'front' as const,
+    flatShading: false,
+    clearcoat: { clearcoat: 1, clearcoatRoughness: 0 },
+    transmission: { transmission: 1, ior: 1.5, thickness: 0.5 },
+    sheen: { sheen: 1, sheenColor: '#ffffff', sheenRoughness: 0.5 },
+    iridescence: {
+      iridescence: 1,
+      iridescenceIOR: 1.3,
+      iridescenceThicknessRange: [100, 400] as [number, number],
+    },
+    displacementScale: 1,
+    displacementBias: 0,
+  },
+
+  light: {
+    color: '#ffffff',
+    intensity: 1,
+    groundColor: '#000000',
+    distance: 0,
+    angle: Math.PI / 6,
+    penumbra: 0,
+    // three.js's own RectAreaLight constructor defaults (area lights only).
+    width: 10,
+    height: 10,
+  },
+
+  camera: {
+    fov: 60,
+    near: 0.1,
+    far: 1000,
+    orthoSize: 5,
+    width: 1920,
+    height: 1080,
+  },
+
+  audio: {
+    spatial: true,
+    volume: 1,
+    refDistance: 1,
+    rolloffFactor: 1,
+    maxDistance: 10000,
+    loop: false,
+    autoplay: false,
+  },
+
+  collider: {
+    cuboid: { halfExtents: [0.5, 0.5, 0.5] as [number, number, number] },
+    ball: { radius: 0.5 },
+    capsule: { radius: 0.25, halfHeight: 0.5 },
+  },
+
+  shadow: {
+    mapSize: 1024,
+  },
+
+  animation: {
+    loop: true,
+  },
+
+  fog: {
+    linear: { near: 1, far: 100 },
+    exponential: { density: 0.01 },
+  },
+
+  environment: {
+    envMapIntensity: 1.0,
+  },
+
+  toneMapping: {
+    // T1.13: the effective renderer default is ACES (see
+    // setup-renderer.ts's `createHostRenderer` + `applyScenePostProcessing`,
+    // which both hardcode `THREE.ACESFilmicToneMapping`/'aces' as the
+    // fallback when a scene omits `environment.toneMapping`) — NOT 'none'.
+    // This used to say 'none', silently disagreeing with the runtime and
+    // with the editor's Tone Mapping inspector dropdown.
+    mode: 'aces' as const,
+    exposure: 1.0,
+  },
+
+  postProcessing: {
+    bloom: { intensity: 1.0, luminanceThreshold: 0.9, luminanceSmoothing: 0.025 },
+    vignette: { darkness: 0.5, offset: 0.5 },
+    brightnessContrast: { brightness: 0, contrast: 0 },
+    hueSaturation: { hue: 0, saturation: 0 },
+    sepia: { intensity: 1.0 },
+    colorDepth: { bits: 16 },
+    chromaticAberration: { offsetX: 0.002, offsetY: 0.002, modulationOffset: 0.15 },
+    lensDistortion: { distortionX: 0, distortionY: 0, focalLengthX: 1, focalLengthY: 1, skew: 0 },
+    depthOfField: { worldFocusDistance: 10, worldFocusRange: 5, bokehScale: 3, focalLength: 0.04 },
+    tiltShift: { offset: 0, rotation: 0, focusArea: 0.4, feather: 0.3 },
+    noise: { premultiply: false },
+    scanline: { density: 1.25 },
+    dotScreen: { angle: 1.57, scale: 1.0 },
+    grid: { scale: 1.0, lineWidth: 0.0 },
+    pixelation: { granularity: 6 },
+    glitch: {
+      delayX: 1.5,
+      delayY: 3.5,
+      durationX: 0.6,
+      durationY: 1.0,
+      strengthX: 0.3,
+      strengthY: 1.0,
+      columns: 0.05,
+      ratio: 0.85,
+    },
+    shockWave: { speed: 2, maxRadius: 1, waveSize: 0.2, amplitude: 0.05 },
+    smaa: { preset: 'high' as const },
+    ssao: { radius: 0.05, intensity: 2.0, bias: 0.025, samples: 16, rings: 7, fade: 0.01 },
+    n8ao: {
+      aoSamples: 16,
+      aoRadius: 5.0,
+      intensity: 5,
+      denoiseSamples: 8,
+      denoiseRadius: 12,
+      distanceFalloff: 1.0,
+    },
+    godRays: { density: 0.96, decay: 0.93, weight: 0.4, exposure: 0.6, samples: 60 },
+    outline: {
+      edgeStrength: 3,
+      pulseSpeed: 0,
+      visibleEdgeColor: '#ffffff',
+      hiddenEdgeColor: '#22090a',
+    },
+    ssr: { intensity: 1, exponent: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+    ssgi: { intensity: 1, distance: 10, thickness: 10, maxRoughness: 1 },
+    motionBlur: { intensity: 1, jitter: 1, samples: 16 },
+  },
+
+  navigation: {
+    cellSize: 0.3,
+    cellHeight: 0.2,
+    walkableSlopeAngle: 45,
+    walkableHeight: 2,
+    walkableClimb: 1,
+    walkableRadius: 0.5,
+    maxEdgeLen: 12,
+    maxSimplificationError: 1.3,
+    minRegionArea: 8,
+    mergeRegionArea: 20,
+  },
+} as const;

package/src/scene/geometries/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in geometry generators. Importing this module for its side effects
+ * registers the built-ins into the geometry registry. Both the runtime factory
+ * (scene-loader) and the editor factory (entity-factory) import it so generated
+ * meshes resolve on whichever side builds first.
+ */
+import './terrain';

package/src/scene/geometries/terrain.ts

@@ -0,0 +1,42 @@
+import * as THREE from 'three';
+import { registerGeometryGenerator } from '../geometry-registry';
+
+/**
+ * Built-in "Terrain" geometry generator — a horizontal heightfield (XZ plane,
+ * height in +Y) displaced by a deterministic sum-of-sines, so it pairs with a
+ * `trimesh` collider for matching terrain physics. Proof material for roadmap #3.
+ *
+ * Params: width, depth (world size), segments (grid resolution per axis),
+ * amplitude (max height), frequency (wave scale). Deterministic — no Math.random.
+ */
+function heightAt(x: number, z: number, amplitude: number, frequency: number): number {
+  return (
+    amplitude *
+    (Math.sin(x * frequency) * 0.5 +
+      Math.cos(z * frequency * 1.3) * 0.3 +
+      Math.sin((x + z) * frequency * 0.5) * 0.2)
+  );
+}
+
+registerGeometryGenerator('Terrain', {
+  build(params) {
+    const width = (params['width'] as number) ?? 40;
+    const depth = (params['depth'] as number) ?? 40;
+    const segments = (params['segments'] as number) ?? 64;
+    const amplitude = (params['amplitude'] as number) ?? 3;
+    const frequency = (params['frequency'] as number) ?? 0.25;
+
+    const geo = new THREE.PlaneGeometry(width, depth, segments, segments);
+    // Lay the plane flat (XZ) with normal +Y, then displace Y by the heightfield.
+    geo.rotateX(-Math.PI / 2);
+    const pos = geo.attributes['position'] as THREE.BufferAttribute;
+    for (let i = 0; i < pos.count; i++) {
+      const x = pos.getX(i);
+      const z = pos.getZ(i);
+      pos.setY(i, heightAt(x, z, amplitude, frequency));
+    }
+    pos.needsUpdate = true;
+    geo.computeVertexNormals();
+    return geo;
+  },
+});

package/src/scene/geometry-registry.ts

@@ -0,0 +1,42 @@
+import type * as THREE from 'three';
+
+/**
+ * A geometry-generator definition. Registered by name and resolved when a scene
+ * mesh declares `{ generator: <name> }`. Mirrors the material/instancer registry
+ * pattern: the generation logic lives here in code, the authored params arrive as
+ * scene data.
+ *
+ * `build` returns a real THREE.BufferGeometry. Paired with a `trimesh` collider,
+ * the generated geometry also drives physics (e.g. terrain), so the visual and
+ * collision surfaces match exactly.
+ */
+export interface GeometryGeneratorDef {
+  build(params: Record<string, unknown>): THREE.BufferGeometry;
+}
+
+const registry = new Map<string, GeometryGeneratorDef>();
+
+/** Register a geometry generator under `name`. */
+export function registerGeometryGenerator(name: string, def: GeometryGeneratorDef): void {
+  registry.set(name, def);
+}
+
+/** Look up a registered geometry generator. */
+export function getGeometryGenerator(name: string): GeometryGeneratorDef | undefined {
+  return registry.get(name);
+}
+
+/**
+ * Build a procedural geometry by registered generator name. Throws if the
+ * generator is unknown (fail loud — same posture as the other registries).
+ */
+export function buildGeneratedGeometry(
+  name: string,
+  params: Record<string, unknown>,
+): THREE.BufferGeometry {
+  const def = registry.get(name);
+  if (!def) {
+    throw new Error(`Geometry generator "${name}" not found in geometry registry`);
+  }
+  return def.build(params ?? {});
+}

package/src/scene/instance-registry.ts

@@ -0,0 +1,84 @@
+import * as THREE from 'three';
+import type { InstancesFile } from './schema/instances';
+
+/**
+ * An instancer definition. Registered by name and resolved when a scene mesh
+ * declares `{ instancer: <name> }`. Mirrors the material-registry pattern: the
+ * generation logic lives here in code (the "behavior" half), the authored params
+ * arrive as scene data (the "data" half).
+ *
+ * `build` returns per-instance LOCAL transforms; the factory packs them into a
+ * single THREE.InstancedMesh, so N instances cost one draw call.
+ */
+export interface InstancerDef {
+  /** Produce per-instance local matrices from authored params. */
+  build(params: Record<string, unknown>): THREE.Matrix4[];
+}
+
+const registry = new Map<string, InstancerDef>();
+
+/** Register an instancer definition under `name`. */
+export function registerInstancer(name: string, def: InstancerDef): void {
+  registry.set(name, def);
+}
+
+/** Look up a registered instancer. */
+export function getInstancer(name: string): InstancerDef | undefined {
+  return registry.get(name);
+}
+
+/**
+ * Build a THREE.InstancedMesh from a registered instancer. Throws if the
+ * instancer is unknown (fail loud — same posture as the component/material
+ * registries). One InstancedMesh = one draw call for all instances.
+ */
+export function buildInstancedMesh(
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material,
+  name: string,
+  params: Record<string, unknown>,
+): THREE.InstancedMesh {
+  const def = registry.get(name);
+  if (!def) {
+    throw new Error(`Instancer "${name}" not found in instancer registry`);
+  }
+  const matrices = def.build(params ?? {});
+  const mesh = new THREE.InstancedMesh(geometry, material, matrices.length);
+  for (let i = 0; i < matrices.length; i++) {
+    mesh.setMatrixAt(i, matrices[i]!);
+  }
+  mesh.instanceMatrix.needsUpdate = true;
+  mesh.userData['__instancer'] = name;
+  return mesh;
+}
+
+/**
+ * Build a THREE.InstancedMesh directly from an already-parsed `.instances.json`
+ * tuple array (F3, docs/VSCN-STRUCTURAL-GAPS-DESIGN.md — the declarative,
+ * authored-data counterpart to `buildInstancedMesh`'s code-registered
+ * instancers). Each tuple is
+ * `[posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ]`. Pure and
+ * synchronous (no fetch) so it's exercisable headlessly by both the scene
+ * loader (after it fetches+parses the asset) and unit tests.
+ */
+export function buildInstancedMeshFromTuples(
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material,
+  tuples: InstancesFile,
+): THREE.InstancedMesh {
+  const mesh = new THREE.InstancedMesh(geometry, material, tuples.length);
+  const pos = new THREE.Vector3();
+  const quat = new THREE.Quaternion();
+  const scale = new THREE.Vector3();
+  const matrix = new THREE.Matrix4();
+  for (let i = 0; i < tuples.length; i++) {
+    const t = tuples[i]!;
+    pos.set(t[0], t[1], t[2]);
+    quat.set(t[3], t[4], t[5], t[6]);
+    scale.set(t[7], t[8], t[9]);
+    matrix.compose(pos, quat, scale);
+    mesh.setMatrixAt(i, matrix);
+  }
+  mesh.instanceMatrix.needsUpdate = true;
+  return mesh;
+}

package/src/scene/instancers/grid.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import { registerInstancer } from '../instance-registry';
+
+/**
+ * Built-in "Grid" instancer — a countX × countZ grid of instances on the XZ
+ * plane, centred on the entity origin, with optional deterministic y-jitter.
+ * Proof material for roadmap #2 (first-class instancing): a 100×100 grid is
+ * 10,000 instances in one draw call.
+ *
+ * Determinism: uses a seeded LCG (not Math.random) so a scene renders the same
+ * layout every load — important for reproducible scenes and tests.
+ */
+registerInstancer('Grid', {
+  build(params) {
+    const countX = (params['countX'] as number) ?? 100;
+    const countZ = (params['countZ'] as number) ?? 100;
+    const spacing = (params['spacing'] as number) ?? 2;
+    const jitter = (params['jitter'] as number) ?? 0;
+    let seed = (params['seed'] as number) ?? 1;
+    const rand = () => {
+      seed = (seed * 1664525 + 1013904223) % 4294967296;
+      return seed / 4294967296;
+    };
+
+    const offX = ((countX - 1) * spacing) / 2;
+    const offZ = ((countZ - 1) * spacing) / 2;
+    const matrices: THREE.Matrix4[] = [];
+    const m = new THREE.Matrix4();
+    for (let x = 0; x < countX; x++) {
+      for (let z = 0; z < countZ; z++) {
+        const y = jitter ? (rand() - 0.5) * jitter : 0;
+        m.makeTranslation(x * spacing - offX, y, z * spacing - offZ);
+        matrices.push(m.clone());
+      }
+    }
+    return matrices;
+  },
+});

package/src/scene/instancers/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in instancer definitions. Importing this module for its side effects
+ * registers the built-ins into the instancer registry. Both the runtime factory
+ * (scene-loader) and the editor factory (entity-factory) import it so instanced
+ * meshes resolve on whichever side builds first.
+ */
+import './grid';

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

@@ -0,0 +1,97 @@
+/**
+ * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ *
+ * `createLight`/`createCamera` used to be duplicated verbatim between the
+ * runtime loader (`scene-loader.ts`) and the editor preview
+ * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
+ * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
+ * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
+ * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ *
+ * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
+ * from a `SceneLight`/`SceneCamera` descriptor, reading its fallbacks from
+ * `DEFAULTS` (the single source of truth for scene default values — see
+ * `scene/defaults.ts`). Both the loader and the editor import it, so they
+ * can no longer disagree.
+ */
+
+import * as THREE from 'three';
+// F2 (docs/VSCN-STRUCTURAL-GAPS-DESIGN.md) — area lights. `RectAreaLight`
+// requires its LTC lookup-texture uniforms initialized once before the first
+// instance is constructed; three.js ships that setup as an addon, not part
+// of core. Imported via the `three/addons/*` alias (package.json `exports`:
+// `"./addons/*": "./examples/jsm/*"` — the identical file as
+// `three/examples/jsm/lights/RectAreaLightUniformsLib.js`) because a literal
+// `/examples/` specifier trips `engine-host-no-game-imports.test.ts`'s
+// game/editor-example guard (a same-substring false positive against this
+// repo's OWN `packages/editor/template/src/examples/` convention, unrelated
+// to three.js's addon folder naming).
+import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';
+import { DEFAULTS } from './defaults';
+import type { SceneCamera, SceneLight } from './scene-types';
+
+let rectAreaLightUniformsInitialized = false;
+
+/** Build a Three.js light from a `SceneLight` descriptor. */
+export function createLight(def: SceneLight): THREE.Light {
+  const d = DEFAULTS.light;
+  const color = def.color ?? d.color;
+  const intensity = def.intensity ?? d.intensity;
+
+  switch (def.type) {
+    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(
+        color,
+        intensity,
+        def.distance ?? d.distance,
+        def.angle ?? d.angle,
+        def.penumbra ?? d.penumbra,
+      );
+    case 'hemisphere':
+      return new THREE.HemisphereLight(color, def.groundColor ?? d.groundColor, intensity);
+    case 'area': {
+      // No shadow map is ever wired for this light (RectAreaLight does not
+      // support shadows in three.js — see the honesty note on the schema
+      // field's .describe(); degrade loudly, not silently).
+      if (!rectAreaLightUniformsInitialized) {
+        RectAreaLightUniformsLib.init();
+        rectAreaLightUniformsInitialized = true;
+      }
+      return new THREE.RectAreaLight(
+        color,
+        intensity,
+        def.width ?? d.width,
+        def.height ?? d.height,
+      );
+    }
+    default:
+      return new THREE.DirectionalLight(color, intensity);
+  }
+}
+
+/** Build a Three.js camera from a `SceneCamera` descriptor. */
+export function createCamera(def: SceneCamera): THREE.Camera {
+  const d = DEFAULTS.camera;
+  const aspect = (def.width ?? d.width) / (def.height ?? d.height);
+  if (def.type === 'orthographic') {
+    const size = def.orthoSize ?? d.orthoSize;
+    return new THREE.OrthographicCamera(
+      -size * aspect,
+      size * aspect,
+      size,
+      -size,
+      def.near ?? d.near,
+      def.far ?? d.far,
+    );
+  }
+  return new THREE.PerspectiveCamera(
+    def.fov ?? d.fov,
+    aspect,
+    def.near ?? d.near,
+    def.far ?? d.far,
+  );
+}