@flighthq/lighting 0.1.0

package/dist/spotLight.js

@@ -0,0 +1,86 @@
+import { createEntity } from '@flighthq/entity';
+import { cloneVector3, createVector3, setVector3 } from '@flighthq/geometry';
+import { SpotLightKind } from '@flighthq/types';
+// Independent copy of a spot light's data, including fresh `position`/`direction` vectors.
+export function cloneSpotLight(source) {
+    return createEntity({
+        castsShadow: source.castsShadow,
+        color: source.color,
+        direction: cloneVector3(source.direction),
+        innerConeCos: source.innerConeCos,
+        intensity: source.intensity,
+        kind: SpotLightKind,
+        normalBias: source.normalBias,
+        outerConeCos: source.outerConeCos,
+        pcfRadius: source.pcfRadius,
+        position: cloneVector3(source.position),
+        range: source.range,
+        shadowBias: source.shadowBias,
+    });
+}
+// Cone-restricted point light. `position`/`direction` are world-space; the cone is stored as the
+// precomputed cosines of its inner and outer half-angles (innerConeCos >= outerConeCos). Color is
+// packed sRgb-albedo RGBA (0xrrggbbaa); defaults to opaque white at unit intensity, at the origin
+// facing down (0, -1, 0), 0-degree inner / 45-degree outer cone, infinite range, shadows off.
+export function createSpotLight(options) {
+    const position = options?.position;
+    const direction = options?.direction;
+    const light = createEntity({
+        castsShadow: options?.castsShadow ?? false,
+        color: options?.color ?? 0xffffffff,
+        direction: direction ? cloneVector3(direction) : createVector3(0, -1, 0),
+        innerConeCos: 1,
+        intensity: options?.intensity ?? 1,
+        kind: SpotLightKind,
+        normalBias: options?.normalBias ?? 0,
+        outerConeCos: 1,
+        pcfRadius: options?.pcfRadius ?? 0,
+        position: position ? cloneVector3(position) : createVector3(0, 0, 0),
+        range: options?.range ?? -1,
+        shadowBias: options?.shadowBias ?? 0,
+    });
+    setSpotLightCone(light, options?.innerConeDegrees ?? 0, options?.outerConeDegrees ?? 45);
+    return light;
+}
+// Reads the inner and outer cone half-angles from precomputed cosines and writes them as degrees
+// into `out`. Provides the round-trip for `createSpotLight` which accepts degrees but stores
+// cosines. The `out` object is a plain `{ innerDegrees, outerDegrees }` struct.
+export function getSpotLightConeDegrees(out, source) {
+    out.innerDegrees = (Math.acos(source.innerConeCos) * 180) / Math.PI;
+    out.outerDegrees = (Math.acos(source.outerConeCos) * 180) / Math.PI;
+}
+// Writes the precomputed cone cosines from inner/outer half-angles given in degrees. A larger
+// half-angle yields a smaller cosine, so the stored invariant innerConeCos >= outerConeCos holds
+// exactly when innerDegrees <= outerDegrees; callers are responsible for ordering their inputs.
+export function setSpotLightCone(out, innerDegrees, outerDegrees) {
+    out.innerConeCos = Math.cos((innerDegrees * Math.PI) / 180);
+    out.outerConeCos = Math.cos((outerDegrees * Math.PI) / 180);
+}
+// Writes a normalized direction into `out.direction`. Normalizes x/y/z before storing.
+// Alias-safe: scalar arguments cannot alias the output vector.
+export function setSpotLightDirection(out, x, y, z) {
+    const lx = x;
+    const ly = y;
+    const lz = z;
+    const len = Math.sqrt(lx * lx + ly * ly + lz * lz);
+    if (len > 0) {
+        setVector3(out.direction, lx / len, ly / len, lz / len);
+    }
+}
+// Writes the normalized direction from `out.position` toward `targetX,targetY,targetZ` into
+// `out.direction`. Derives `direction` from a target point — the most common authoring gesture.
+// If `out.position` equals the target (zero-length direction), `direction` is left unchanged.
+export function setSpotLightTarget(out, targetX, targetY, targetZ) {
+    // Read position into locals before writing direction for alias safety.
+    const px = out.position.x;
+    const py = out.position.y;
+    const pz = out.position.z;
+    const dx = targetX - px;
+    const dy = targetY - py;
+    const dz = targetZ - pz;
+    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (len > 0) {
+        setVector3(out.direction, dx / len, dy / len, dz / len);
+    }
+}
+//# sourceMappingURL=spotLight.js.map

package/dist/spotLight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spotLight.js","sourceRoot":"","sources":["../src/spotLight.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/lighting",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Light descriptors: ambient/directional/point/spot/hemisphere/area and environment",
+  "sideEffects": false
+}

package/src/ambientLight.test.ts

@@ -0,0 +1,29 @@
+import { AmbientLightKind } from '@flighthq/types';
+
+import { cloneAmbientLight, createAmbientLight } from './ambientLight';
+
+describe('cloneAmbientLight', () => {
+  it('creates an independent copy with the same fields', () => {
+    const light = createAmbientLight({ color: 0x112233ff, intensity: 0.5 });
+    const copy = cloneAmbientLight(light);
+    expect(copy).not.toBe(light);
+    expect(copy.color).toBe(0x112233ff);
+    expect(copy.intensity).toBe(0.5);
+    expect(copy.kind).toBe(AmbientLightKind);
+  });
+});
+
+describe('createAmbientLight', () => {
+  it('applies opaque-white defaults at unit intensity', () => {
+    const light = createAmbientLight();
+    expect(light.color).toBe(0xffffffff);
+    expect(light.intensity).toBe(1);
+    expect(light.kind).toBe(AmbientLightKind);
+  });
+
+  it('overrides color and intensity from options', () => {
+    const light = createAmbientLight({ color: 0x00ff00ff, intensity: 2 });
+    expect(light.color).toBe(0x00ff00ff);
+    expect(light.intensity).toBe(2);
+  });
+});

package/src/areaLight.test.ts

@@ -0,0 +1,100 @@
+import { createVector3 } from '@flighthq/geometry';
+import { AreaLightKind } from '@flighthq/types';
+
+import { cloneAreaLight, createAreaLight, setAreaLightOrientation } from './areaLight';
+
+describe('cloneAreaLight', () => {
+  it('creates an independent copy with fresh position/direction/right/up vectors', () => {
+    const light = createAreaLight({
+      castsShadow: true,
+      color: 0x112233ff,
+      direction: createVector3(0, 0, -1),
+      intensity: 0.5,
+      normalBias: 0.1,
+      pcfRadius: 2,
+      position: createVector3(1, 2, 3),
+      range: 8,
+      right: createVector3(2, 0, 0),
+      shadowBias: 0.01,
+      up: createVector3(0, 3, 0),
+    });
+    const copy = cloneAreaLight(light);
+    expect(copy).not.toBe(light);
+    expect(copy.position).not.toBe(light.position);
+    expect(copy.direction).not.toBe(light.direction);
+    expect(copy.right).not.toBe(light.right);
+    expect(copy.up).not.toBe(light.up);
+    expect(copy.castsShadow).toBe(true);
+    expect(copy.color).toBe(0x112233ff);
+    expect(copy.direction.z).toBe(-1);
+    expect(copy.intensity).toBe(0.5);
+    expect(copy.normalBias).toBe(0.1);
+    expect(copy.pcfRadius).toBe(2);
+    expect(copy.position.y).toBe(2);
+    expect(copy.range).toBe(8);
+    expect(copy.right.x).toBe(2);
+    expect(copy.shadowBias).toBe(0.01);
+    expect(copy.up.y).toBe(3);
+    expect(copy.kind).toBe(AreaLightKind);
+  });
+});
+
+describe('createAreaLight', () => {
+  it('applies defaults: white, unit intensity, origin facing down, unit half-extents', () => {
+    const light = createAreaLight();
+    expect(light.castsShadow).toBe(false);
+    expect(light.color).toBe(0xffffffff);
+    expect(light.direction.y).toBe(-1);
+    expect(light.intensity).toBe(1);
+    expect(light.normalBias).toBe(0);
+    expect(light.pcfRadius).toBe(0);
+    expect(light.position.x).toBe(0);
+    expect(light.range).toBe(-1);
+    expect(light.right.x).toBe(1);
+    expect(light.shadowBias).toBe(0);
+    expect(light.up.z).toBe(1);
+    expect(light.kind).toBe(AreaLightKind);
+  });
+
+  it('copies the supplied vectors rather than aliasing them', () => {
+    const right = createVector3(4, 0, 0);
+    const up = createVector3(0, 0, 5);
+    const light = createAreaLight({ right, up });
+    expect(light.right).not.toBe(right);
+    expect(light.up).not.toBe(up);
+    expect(light.right.x).toBe(4);
+    expect(light.up.z).toBe(5);
+  });
+});
+
+describe('setAreaLightOrientation', () => {
+  it('updates the direction, right, and up axes while preserving half-extent lengths', () => {
+    // right has length 3, up has length 4 — half-extents should survive the orientation update.
+    const light = createAreaLight({
+      direction: createVector3(0, -1, 0),
+      right: createVector3(3, 0, 0),
+      up: createVector3(0, 0, 4),
+    });
+    setAreaLightOrientation(light, createVector3(0, 0, -1), createVector3(1, 0, 0), createVector3(0, 1, 0));
+    // Direction should now point into -z.
+    expect(light.direction.z).toBeCloseTo(-1, 6);
+    // Right and up half-extent lengths should be preserved.
+    const rightLen = Math.sqrt(light.right.x ** 2 + light.right.y ** 2 + light.right.z ** 2);
+    const upLen = Math.sqrt(light.up.x ** 2 + light.up.y ** 2 + light.up.z ** 2);
+    expect(rightLen).toBeCloseTo(3, 5);
+    expect(upLen).toBeCloseTo(4, 5);
+  });
+
+  it('ignores zero-length input vectors', () => {
+    const light = createAreaLight({
+      direction: createVector3(0, -1, 0),
+      right: createVector3(1, 0, 0),
+      up: createVector3(0, 0, 1),
+    });
+    setAreaLightOrientation(light, createVector3(0, 0, 0), createVector3(0, 0, 0), createVector3(0, 0, 0));
+    // All vectors unchanged when all inputs are zero.
+    expect(light.direction.y).toBeCloseTo(-1, 6);
+    expect(light.right.x).toBeCloseTo(1, 6);
+    expect(light.up.z).toBeCloseTo(1, 6);
+  });
+});

package/src/colorFromKelvin.test.ts

@@ -0,0 +1,48 @@
+import { createColorFromKelvin } from './colorFromKelvin';
+
+describe('createColorFromKelvin', () => {
+  it('returns opaque alpha (0xff) for all temperatures', () => {
+    expect(createColorFromKelvin(3000) & 0xff).toBe(0xff);
+    expect(createColorFromKelvin(6500) & 0xff).toBe(0xff);
+    expect(createColorFromKelvin(10000) & 0xff).toBe(0xff);
+  });
+
+  it('returns white (0xffffffff) for D65 daylight (~6500 K)', () => {
+    const color = createColorFromKelvin(6500);
+    const r = (color >>> 24) & 0xff;
+    const g = (color >>> 16) & 0xff;
+    const b = (color >>> 8) & 0xff;
+    // D65 should be close to neutral white — all channels near 255.
+    expect(r).toBeGreaterThan(240);
+    expect(g).toBeGreaterThan(240);
+    expect(b).toBeGreaterThan(230);
+  });
+
+  it('produces warmer (more red, less blue) color for lower temperatures', () => {
+    const warm = createColorFromKelvin(2000);
+    const cool = createColorFromKelvin(10000);
+    const warmR = (warm >>> 24) & 0xff;
+    const warmB = (warm >>> 8) & 0xff;
+    const coolR = (cool >>> 24) & 0xff;
+    const coolB = (cool >>> 8) & 0xff;
+    // Warm candlelight should have more red and less blue than cool sky light.
+    expect(warmR).toBeGreaterThanOrEqual(coolR);
+    expect(warmB).toBeLessThanOrEqual(coolB);
+  });
+
+  it('clamps inputs below 1000 K to 1000 K', () => {
+    expect(createColorFromKelvin(500)).toBe(createColorFromKelvin(1000));
+  });
+
+  it('clamps inputs above 40000 K to 40000 K', () => {
+    expect(createColorFromKelvin(50000)).toBe(createColorFromKelvin(40000));
+  });
+
+  it('returns a valid packed RGBA integer (unsigned 32-bit)', () => {
+    const color = createColorFromKelvin(5500);
+    expect(color).toBeGreaterThanOrEqual(0);
+    expect(color).toBeLessThanOrEqual(0xffffffff);
+    // Must be an integer.
+    expect(color % 1).toBe(0);
+  });
+});

package/src/directionalLight.test.ts

@@ -0,0 +1,89 @@
+import { createVector3 } from '@flighthq/geometry';
+import { DirectionalLightKind } from '@flighthq/types';
+
+import {
+  cloneDirectionalLight,
+  createDirectionalLight,
+  setDirectionalLightDirection,
+  setDirectionalLightTarget,
+} from './directionalLight';
+
+describe('cloneDirectionalLight', () => {
+  it('creates an independent copy with a fresh direction vector', () => {
+    const light = createDirectionalLight({
+      castsShadow: true,
+      color: 0x112233ff,
+      direction: createVector3(1, 0, 0),
+      intensity: 0.5,
+      normalBias: 0.1,
+      pcfRadius: 2,
+      shadowBias: 0.01,
+    });
+    const copy = cloneDirectionalLight(light);
+    expect(copy).not.toBe(light);
+    expect(copy.direction).not.toBe(light.direction);
+    expect(copy.castsShadow).toBe(true);
+    expect(copy.color).toBe(0x112233ff);
+    expect(copy.direction.x).toBe(1);
+    expect(copy.intensity).toBe(0.5);
+    expect(copy.normalBias).toBe(0.1);
+    expect(copy.pcfRadius).toBe(2);
+    expect(copy.shadowBias).toBe(0.01);
+    expect(copy.kind).toBe(DirectionalLightKind);
+  });
+});
+
+describe('createDirectionalLight', () => {
+  it('applies defaults: white, unit intensity, downward, shadows off', () => {
+    const light = createDirectionalLight();
+    expect(light.castsShadow).toBe(false);
+    expect(light.color).toBe(0xffffffff);
+    expect(light.direction.x).toBe(0);
+    expect(light.direction.y).toBe(-1);
+    expect(light.direction.z).toBe(0);
+    expect(light.intensity).toBe(1);
+    expect(light.normalBias).toBe(0);
+    expect(light.pcfRadius).toBe(0);
+    expect(light.shadowBias).toBe(0);
+    expect(light.kind).toBe(DirectionalLightKind);
+  });
+
+  it('copies the supplied direction rather than aliasing it', () => {
+    const direction = createVector3(0, 0, 1);
+    const light = createDirectionalLight({ direction });
+    expect(light.direction).not.toBe(direction);
+    expect(light.direction.z).toBe(1);
+  });
+});
+
+describe('setDirectionalLightDirection', () => {
+  it('writes a normalized direction into the light', () => {
+    const light = createDirectionalLight();
+    setDirectionalLightDirection(light, 0, 0, 3);
+    expect(light.direction.x).toBeCloseTo(0, 6);
+    expect(light.direction.y).toBeCloseTo(0, 6);
+    expect(light.direction.z).toBeCloseTo(1, 6);
+  });
+
+  it('leaves direction unchanged for a zero-length input', () => {
+    const light = createDirectionalLight({ direction: createVector3(0, -1, 0) });
+    setDirectionalLightDirection(light, 0, 0, 0);
+    expect(light.direction.y).toBeCloseTo(-1, 6);
+  });
+});
+
+describe('setDirectionalLightTarget', () => {
+  it('sets direction toward the target from the from-point', () => {
+    const light = createDirectionalLight();
+    setDirectionalLightTarget(light, 0, 0, 0, 0, 0, 5);
+    expect(light.direction.x).toBeCloseTo(0, 6);
+    expect(light.direction.y).toBeCloseTo(0, 6);
+    expect(light.direction.z).toBeCloseTo(1, 6);
+  });
+
+  it('leaves direction unchanged when from equals to', () => {
+    const light = createDirectionalLight({ direction: createVector3(0, -1, 0) });
+    setDirectionalLightTarget(light, 1, 2, 3, 1, 2, 3);
+    expect(light.direction.y).toBeCloseTo(-1, 6);
+  });
+});

package/src/environment.test.ts

@@ -0,0 +1,49 @@
+import { createEntity } from '@flighthq/entity';
+import type { CubeTexture, Sampler } from '@flighthq/types';
+import { EnvironmentKind } from '@flighthq/types';
+
+import { cloneEnvironment, createEnvironment } from './environment';
+
+function createTestCubeTexture(): CubeTexture {
+  const sampler: Sampler = createEntity({
+    anisotropy: 1,
+    magFilter: 'linear',
+    minFilter: 'linear',
+    mipmaps: false,
+    wrapU: 'clamp-to-edge',
+    wrapV: 'clamp-to-edge',
+  });
+  return createEntity({
+    colorSpace: 'linear',
+    faces: [null, null, null, null, null, null],
+    sampler,
+  });
+}
+
+describe('cloneEnvironment', () => {
+  it('creates an independent copy that shares the cubemap reference', () => {
+    const cube = createTestCubeTexture();
+    const environment = createEnvironment({ environment: cube, intensity: 0.5 });
+    const copy = cloneEnvironment(environment);
+    expect(copy).not.toBe(environment);
+    expect(copy.environment).toBe(cube);
+    expect(copy.intensity).toBe(0.5);
+    expect(copy.kind).toBe(EnvironmentKind);
+  });
+});
+
+describe('createEnvironment', () => {
+  it('applies defaults: no cubemap at unit intensity', () => {
+    const environment = createEnvironment();
+    expect(environment.environment).toBeNull();
+    expect(environment.intensity).toBe(1);
+    expect(environment.kind).toBe(EnvironmentKind);
+  });
+
+  it('stores the supplied cubemap and intensity', () => {
+    const cube = createTestCubeTexture();
+    const environment = createEnvironment({ environment: cube, intensity: 2 });
+    expect(environment.environment).toBe(cube);
+    expect(environment.intensity).toBe(2);
+  });
+});

package/src/hemisphereLight.test.ts

@@ -0,0 +1,31 @@
+import { HemisphereLightKind } from '@flighthq/types';
+
+import { cloneHemisphereLight, createHemisphereLight } from './hemisphereLight';
+
+describe('cloneHemisphereLight', () => {
+  it('creates an independent copy with the same fields', () => {
+    const light = createHemisphereLight({ groundColor: 0x223344ff, intensity: 0.5, skyColor: 0x8899aaff });
+    const copy = cloneHemisphereLight(light);
+    expect(copy).not.toBe(light);
+    expect(copy.groundColor).toBe(0x223344ff);
+    expect(copy.intensity).toBe(0.5);
+    expect(copy.skyColor).toBe(0x8899aaff);
+    expect(copy.kind).toBe(HemisphereLightKind);
+  });
+});
+
+describe('createHemisphereLight', () => {
+  it('applies opaque-white defaults at unit intensity for both colors', () => {
+    const light = createHemisphereLight();
+    expect(light.groundColor).toBe(0xffffffff);
+    expect(light.intensity).toBe(1);
+    expect(light.skyColor).toBe(0xffffffff);
+    expect(light.kind).toBe(HemisphereLightKind);
+  });
+
+  it('overrides sky and ground colors from options', () => {
+    const light = createHemisphereLight({ groundColor: 0x000000ff, skyColor: 0x0000ffff });
+    expect(light.groundColor).toBe(0x000000ff);
+    expect(light.skyColor).toBe(0x0000ffff);
+  });
+});

package/src/lightAnalysis.test.ts

@@ -0,0 +1,188 @@
+import { createBoundingSphere } from '@flighthq/geometry';
+
+import { createAmbientLight } from './ambientLight';
+import { createAreaLight } from './areaLight';
+import { createDirectionalLight } from './directionalLight';
+import { createEnvironment } from './environment';
+import { createHemisphereLight } from './hemisphereLight';
+import {
+  getLightInfluenceBounds,
+  getLightLuminance,
+  hasLightInfluenceOnBounds,
+  isLightShadowCasting,
+} from './lightAnalysis';
+import { createPointLight } from './pointLight';
+import { createSpotLight } from './spotLight';
+
+describe('getLightInfluenceBounds', () => {
+  it('returns sentinel radius (-1) for ambient lights', () => {
+    const light = createAmbientLight();
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.radius).toBe(-1);
+  });
+
+  it('returns sentinel radius for hemisphere lights', () => {
+    const light = createHemisphereLight();
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.radius).toBe(-1);
+  });
+
+  it('returns sentinel radius for directional lights', () => {
+    const light = createDirectionalLight();
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.radius).toBe(-1);
+  });
+
+  it('returns sentinel radius for environment lights', () => {
+    const light = createEnvironment();
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.radius).toBe(-1);
+  });
+
+  it('returns sentinel radius for infinite-range point light', () => {
+    const light = createPointLight({ range: -1 });
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.radius).toBe(-1);
+  });
+
+  it('returns position + range sphere for finite-range point light', () => {
+    const light = createPointLight({ position: { x: 1, y: 2, z: 3 }, range: 5 });
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.center.x).toBe(1);
+    expect(out.center.y).toBe(2);
+    expect(out.center.z).toBe(3);
+    expect(out.radius).toBe(5);
+  });
+
+  it('returns position + range sphere for finite-range spot light', () => {
+    const light = createSpotLight({ position: { x: 0, y: 10, z: 0 }, range: 8 });
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.center.y).toBe(10);
+    expect(out.radius).toBe(8);
+  });
+
+  it('returns position + range sphere for finite-range area light', () => {
+    const light = createAreaLight({ position: { x: 5, y: 0, z: 0 }, range: 3 });
+    const out = createBoundingSphere();
+    getLightInfluenceBounds(out, light);
+    expect(out.center.x).toBe(5);
+    expect(out.radius).toBe(3);
+  });
+});
+
+describe('getLightLuminance', () => {
+  it('returns 0 for lights without a color field', () => {
+    const light = createEnvironment({ intensity: 5 });
+    // Environment has no color field — luminance should fall back to 0.
+    // (environment light has no color field in its type; cast to bypass type)
+    expect(getLightLuminance(light)).toBe(0);
+  });
+
+  it('returns zero for black (0x000000ff)', () => {
+    const light = createAmbientLight({ color: 0x000000ff, intensity: 1 });
+    expect(getLightLuminance(light)).toBeCloseTo(0, 6);
+  });
+
+  it('returns nonzero luminance for white at unit intensity', () => {
+    const light = createAmbientLight({ color: 0xffffffff, intensity: 1 });
+    expect(getLightLuminance(light)).toBeCloseTo(1, 4);
+  });
+
+  it('scales luminance by intensity', () => {
+    const a = createAmbientLight({ color: 0xffffffff, intensity: 2 });
+    const b = createAmbientLight({ color: 0xffffffff, intensity: 4 });
+    expect(getLightLuminance(b) / getLightLuminance(a)).toBeCloseTo(2, 4);
+  });
+
+  it('uses BT.709 green weighting (green > red > blue)', () => {
+    const red = createAmbientLight({ color: 0xff0000ff, intensity: 1 });
+    const green = createAmbientLight({ color: 0x00ff00ff, intensity: 1 });
+    const blue = createAmbientLight({ color: 0x0000ffff, intensity: 1 });
+    expect(getLightLuminance(green)).toBeGreaterThan(getLightLuminance(red));
+    expect(getLightLuminance(red)).toBeGreaterThan(getLightLuminance(blue));
+  });
+});
+
+describe('hasLightInfluenceOnBounds', () => {
+  it('returns true for ambient lights (unlimited reach)', () => {
+    const light = createAmbientLight();
+    const bounds = createBoundingSphere(100, 0, 0, 1);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(true);
+  });
+
+  it('returns true for directional lights (unlimited reach)', () => {
+    const light = createDirectionalLight();
+    const bounds = createBoundingSphere(1000, 0, 0, 1);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(true);
+  });
+
+  it('returns true for overlapping point light and bounds', () => {
+    const light = createPointLight({ position: { x: 0, y: 0, z: 0 }, range: 10 });
+    const bounds = createBoundingSphere(5, 0, 0, 2);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(true);
+  });
+
+  it('returns false for non-overlapping point light and bounds', () => {
+    const light = createPointLight({ position: { x: 0, y: 0, z: 0 }, range: 5 });
+    const bounds = createBoundingSphere(20, 0, 0, 1);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(false);
+  });
+
+  it('returns false for empty bounds (radius < 0)', () => {
+    const light = createPointLight({ position: { x: 0, y: 0, z: 0 }, range: 10 });
+    const bounds = createBoundingSphere(0, 0, 0, -1);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(false);
+  });
+
+  it('returns true for infinite-range point light regardless of distance', () => {
+    const light = createPointLight({ position: { x: 0, y: 0, z: 0 }, range: -1 });
+    const bounds = createBoundingSphere(999, 0, 0, 1);
+    expect(hasLightInfluenceOnBounds(light, bounds)).toBe(true);
+  });
+});
+
+describe('isLightShadowCasting', () => {
+  it('returns false for ambient lights', () => {
+    expect(isLightShadowCasting(createAmbientLight())).toBe(false);
+  });
+
+  it('returns false for hemisphere lights', () => {
+    expect(isLightShadowCasting(createHemisphereLight())).toBe(false);
+  });
+
+  it('returns false for environment lights', () => {
+    expect(isLightShadowCasting(createEnvironment())).toBe(false);
+  });
+
+  it('returns false for directional lights with castsShadow: false', () => {
+    const light = createDirectionalLight({ castsShadow: false });
+    expect(isLightShadowCasting(light)).toBe(false);
+  });
+
+  it('returns true for directional lights with castsShadow: true', () => {
+    const light = createDirectionalLight({ castsShadow: true });
+    expect(isLightShadowCasting(light)).toBe(true);
+  });
+
+  it('returns true for point lights with castsShadow: true', () => {
+    const light = createPointLight({ castsShadow: true });
+    expect(isLightShadowCasting(light)).toBe(true);
+  });
+
+  it('returns true for spot lights with castsShadow: true', () => {
+    const light = createSpotLight({ castsShadow: true });
+    expect(isLightShadowCasting(light)).toBe(true);
+  });
+
+  it('returns true for area lights with castsShadow: true', () => {
+    const light = createAreaLight({ castsShadow: true });
+    expect(isLightShadowCasting(light)).toBe(true);
+  });
+});