@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/lighting/colorIntensity.js

@@ -0,0 +1,177 @@
+import { clamp, finite, isPlainObject, vector } from './utils.js';
+
+export const LIGHT_INTENSITY_UNITS = Object.freeze([
+  'unitless',
+  'lux',
+  'candela',
+  'lumens',
+  'nits',
+]);
+
+const DEFAULT_UNIT_BY_TYPE = Object.freeze({
+  ambient: 'unitless',
+  discArea: 'nits',
+  directional: 'lux',
+  hemisphere: 'unitless',
+  point: 'candela',
+  rectArea: 'nits',
+  spot: 'candela',
+  tubeArea: 'nits',
+});
+
+function channelToHex(value) {
+  return Number.parseInt(value, 16) / 255;
+}
+
+function parseHexColor(value) {
+  const hex = String(value).trim().replace(/^#/, '');
+  if (/^[0-9a-f]{3}$/i.test(hex)) {
+    return [...hex].map((channel) => channelToHex(`${channel}${channel}`));
+  }
+  if (/^[0-9a-f]{6}$/i.test(hex)) {
+    return [channelToHex(hex.slice(0, 2)), channelToHex(hex.slice(2, 4)), channelToHex(hex.slice(4, 6))];
+  }
+  return null;
+}
+
+/**
+ * Approximates a black-body color in authoring-space sRGB.
+ * The useful range is deliberately clamped to 1,000-40,000 kelvin.
+ */
+export function colorTemperatureToRgb(temperatureKelvin, { clampOutput = true } = {}) {
+  const temperature = clamp(finite(temperatureKelvin, 6500), 1000, 40000) / 100;
+  let red;
+  let green;
+  let blue;
+
+  if (temperature <= 66) {
+    red = 255;
+    green = 99.4708025861 * Math.log(temperature) - 161.1195681661;
+    blue = temperature <= 19
+      ? 0
+      : 138.5177312231 * Math.log(temperature - 10) - 305.0447927307;
+  } else {
+    red = 329.698727446 * ((temperature - 60) ** -0.1332047592);
+    green = 288.1221695283 * ((temperature - 60) ** -0.0755148492);
+    blue = 255;
+  }
+
+  const rgb = [red / 255, green / 255, blue / 255];
+  return clampOutput ? rgb.map((channel) => clamp(channel, 0, 1)) : rgb;
+}
+
+/** Converts an RGB array, hex color, or temperature/tint object to sRGB. */
+export function resolveLightColor(value = [1, 1, 1]) {
+  if (typeof value === 'string') return parseHexColor(value) ?? [1, 1, 1];
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return [((value >> 16) & 255) / 255, ((value >> 8) & 255) / 255, (value & 255) / 255];
+  }
+  if (Array.isArray(value)) return vector(value, [1, 1, 1], 3).map((channel) => clamp(channel, 0, 1));
+  if (!isPlainObject(value)) return [1, 1, 1];
+
+  const base = value.temperatureKelvin !== null && value.temperatureKelvin !== undefined
+    ? colorTemperatureToRgb(value.temperatureKelvin)
+    : resolveLightColor(value.rgb ?? value.color ?? [1, 1, 1]);
+  const tint = vector(value.tint, [1, 1, 1], 3);
+  return base.map((channel, index) => clamp(channel * tint[index], 0, 1));
+}
+
+/** Normalizes author-facing light color metadata into a serializable object. */
+export function createLightColor(value = null) {
+  if (isPlainObject(value)) {
+    const temperature = value.temperatureKelvin === null || value.temperatureKelvin === undefined
+      ? null
+      : clamp(finite(value.temperatureKelvin, 6500), 1000, 40000);
+    return {
+      rgb: temperature === null ? resolveLightColor(value.rgb ?? value.color ?? [1, 1, 1]) : null,
+      temperatureKelvin: temperature,
+      tint: vector(value.tint, [1, 1, 1], 3).map((channel) => Math.max(channel, 0)),
+    };
+  }
+  return {
+    rgb: resolveLightColor(value ?? [1, 1, 1]),
+    temperatureKelvin: null,
+    tint: [1, 1, 1],
+  };
+}
+
+/** Converts luminous flux to intensity for an isotropic point source. */
+export function lumensToCandela(lumens, solidAngleSteradians = Math.PI * 4) {
+  return Math.max(finite(lumens, 0), 0) / Math.max(finite(solidAngleSteradians, Math.PI * 4), 1e-6);
+}
+
+/** Converts candela to luminous flux for a supplied solid angle. */
+export function candelaToLumens(candela, solidAngleSteradians = Math.PI * 4) {
+  return Math.max(finite(candela, 0), 0) * Math.max(finite(solidAngleSteradians, Math.PI * 4), 0);
+}
+
+/** Solid angle of a cone whose half-angle is `angleRadians`. */
+export function coneSolidAngle(angleRadians) {
+  return Math.PI * 2 * (1 - Math.cos(clamp(finite(angleRadians, Math.PI / 4), 0.001, Math.PI / 2)));
+}
+
+/** Illuminance in lux from a candela value at a distance in meters. */
+export function luxAtDistance(candela, distanceMeters) {
+  const distance = Math.max(finite(distanceMeters, 1), 0.001);
+  return Math.max(finite(candela, 0), 0) / (distance * distance);
+}
+
+/** Approximate luminance for a diffuse rectangular emitter. */
+export function lumensToNits(lumens, widthMeters = 1, heightMeters = 1) {
+  const area = Math.max(finite(widthMeters, 1) * finite(heightMeters, 1), 1e-6);
+  return Math.max(finite(lumens, 0), 0) / (Math.PI * area);
+}
+
+/**
+ * Normalizes physical intensity metadata. `artisticMultiplier` remains
+ * separate so a look can be tuned without destroying authored units.
+ */
+export function createLightIntensity(type, value = null) {
+  const defaultUnit = DEFAULT_UNIT_BY_TYPE[type] ?? 'unitless';
+  if (typeof value === 'number') {
+    return { artisticMultiplier: 1, referenceDistance: 1, unit: defaultUnit, value: Math.max(value, 0) };
+  }
+  const source = isPlainObject(value) ? value : {};
+  const unit = LIGHT_INTENSITY_UNITS.includes(source.unit) ? source.unit : defaultUnit;
+  return {
+    artisticMultiplier: Math.max(finite(source.artisticMultiplier, source.multiplier ?? 1), 0),
+    referenceDistance: Math.max(finite(source.referenceDistance, 1), 0.001),
+    unit,
+    value: Math.max(finite(source.value, 1), 0),
+  };
+}
+
+/**
+ * Resolves portable intensity metadata to the value expected by Three.js.
+ * Directional lux, local-light candela, and rect-area nits pass through.
+ * Conversions from lumens are geometric approximations, not photometry.
+ */
+export function resolveThreeLightIntensity(type, intensity, geometry = {}) {
+  const resolved = createLightIntensity(type, intensity);
+  const { artisticMultiplier, referenceDistance, unit, value } = resolved;
+  let output = value;
+
+  if (type === 'point') {
+    if (unit === 'lumens') output = lumensToCandela(value);
+    if (unit === 'lux') output = value * referenceDistance * referenceDistance;
+    if (unit === 'nits') output = value;
+  } else if (type === 'spot') {
+    if (unit === 'lumens') output = lumensToCandela(value, coneSolidAngle(geometry.angle));
+    if (unit === 'lux') output = value * referenceDistance * referenceDistance;
+    if (unit === 'nits') output = value;
+  } else if (type === 'rectArea' || type === 'discArea' || type === 'tubeArea') {
+    if (unit === 'lumens') output = lumensToNits(value, geometry.width, geometry.height);
+    if (unit === 'candela') {
+      const area = Math.max(finite(geometry.width, 1) * finite(geometry.height, 1), 1e-6);
+      output = value / area;
+    }
+    if (unit === 'lux') output = value / Math.PI;
+  }
+
+  return Math.max(output * artisticMultiplier, 0);
+}
+
+/** Returns the preferred authoring unit for a descriptor type. */
+export function getDefaultIntensityUnit(type) {
+  return DEFAULT_UNIT_BY_TYPE[type] ?? 'unitless';
+}

package/src/lighting/index.js

@@ -0,0 +1,161 @@
+// Public lighting-authoring surface. Kept as a subpath-ready cluster so hosts
+// can use JSON documents and Unreal export without constructing a renderer.
+
+export {
+  LIGHT_INTENSITY_UNITS,
+  candelaToLumens,
+  colorTemperatureToRgb,
+  coneSolidAngle,
+  createLightColor,
+  createLightIntensity,
+  getDefaultIntensityUnit,
+  lumensToCandela,
+  lumensToNits,
+  luxAtDistance,
+  resolveLightColor,
+  resolveThreeLightIntensity,
+} from './colorIntensity.js';
+
+export {
+  COOKIE_CAPABLE_LIGHT_TYPES,
+  LIGHT_TYPES,
+  SHADOW_CAPABLE_LIGHT_TYPES,
+  createAmbientLightDescriptor,
+  createDirectionalLightDescriptor,
+  createDiscAreaLightDescriptor,
+  createHemisphereLightDescriptor,
+  createLightArtisticSettings,
+  createLightCookie,
+  createLightDescriptor,
+  createLightIesProfile,
+  createLightLinking,
+  createLightShadow,
+  createPointLightDescriptor,
+  createRectAreaLightDescriptor,
+  createSpotLightDescriptor,
+  createTubeAreaLightDescriptor,
+  mergeLightDescriptor,
+  validateLightDescriptor,
+} from './lightDescriptors.js';
+
+export {
+  LIGHTING_LOOK_DOCUMENT_TYPE,
+  LIGHTING_LOOK_SCHEMA_VERSION,
+  LIGHTING_RECIPE_DOCUMENT_TYPE,
+  LIGHTING_RECIPE_SCHEMA_VERSION,
+  SHADOW_POLICY_MODES,
+  SHADOW_UPDATE_MODES,
+  assertLightingLook,
+  assertLightingRecipe,
+  createLightingLook,
+  createLightingLookPreset,
+  createLightingRecipe,
+  createShadowPolicy,
+  deserializeLightingLook,
+  deserializeLightingLookPreset,
+  deserializeLightingRecipe,
+  serializeLightingLook,
+  serializeLightingLookPreset,
+  serializeLightingRecipe,
+  validateLightingLook,
+  validateLightingLookPreset,
+  validateLightingRecipe,
+} from './lightingDocuments.js';
+
+export {
+  LIGHTING_LOOK_PRESETS,
+  LIGHTING_LUMINAIRE_PRESETS,
+  LIGHTING_QUALITY_PRESETS,
+  LIGHTING_RIG_PRESETS,
+  createLightingQualityProfile,
+  getLightingPresetOptions,
+  resolveLightingLookPreset,
+  resolveLightingPreset,
+  resolveLightingQualityPreset,
+  resolveLightingRigPreset,
+  resolveLuminairePreset,
+} from './lightingPresets.js';
+
+export {
+  createLightingCapabilityReport,
+  getLightingTypeCapability,
+  snapshotLightingCapabilities,
+} from './lightingCapabilities.js';
+
+export {
+  createLightingManager,
+  createLightingRig,
+  ensureAreaLightSupport,
+  getAreaLightSupportState,
+  realizeLightingRecipe,
+} from './lightingRuntime.js';
+
+export {
+  LIGHTING_STYLE_APPLY_METADATA,
+  LIGHTING_STYLE_DOCUMENT_TYPE,
+  LIGHTING_STYLE_SCHEMA_VERSION,
+  createLightingStylePresetDocument,
+  createLightingStyleSettings,
+  getLightingStylePresetOptions,
+  parseLightingStylePresetDocument,
+  registerLightingStylePreset,
+  registerLightingStylePresetDocument,
+  resolveLightingStylePreset,
+  sampleLightingStyle,
+  sanitizeLightingStyleSettings,
+  serializeLightingStylePresetDocument,
+  validateLightingStylePresetDocument,
+} from './lightingStyle.js';
+
+export {
+  FIXTURE_SCHEDULE_MODES,
+  LIGHT_FIXTURE_APPLY_METADATA,
+  LIGHT_FIXTURE_DOCUMENT_TYPE,
+  LIGHT_FIXTURE_SCHEMA_VERSION,
+  createLightFixtureDocument,
+  createLightFixtureSettings,
+  getLightFixtureOptions,
+  parseLightFixtureDocument,
+  registerLightFixture,
+  registerLightFixtureDocument,
+  resolveFixturePlacement,
+  resolveLightFixture,
+  sanitizeLightFixtureSettings,
+  serializeLightFixtureDocument,
+  validateLightFixtureDocument,
+} from './lightingFixtures.js';
+
+export { createLightingSystem } from './lightingSystem.js';
+
+export {
+  DEFAULT_LIGHTING_STYLE_DOMAINS,
+  DEFAULT_LIGHT_FIXTURE_DOMAINS,
+  LIGHTING_STYLE_GENERATOR_DOMAIN,
+  LIGHT_FIXTURE_GENERATOR_DOMAIN,
+  buildLightFixtureFromSample,
+  buildLightingStyleFromSample,
+  createGeneratedLightFixtureDocument,
+  createGeneratedLightingStyleDocument,
+  createLightFixtureGeneratorRecipe,
+  createLightingStyleGeneratorRecipe,
+  getLightFixtureGeneratorFamilyOptions,
+  getLightingStyleGeneratorFamilyOptions,
+  parseLightFixtureGeneratorRecipe,
+  parseLightingStyleGeneratorRecipe,
+  registerLightFixtureGeneratorFamily,
+  registerLightingStyleGeneratorFamily,
+  resolveLightFixtureGeneratorRecipe,
+  resolveLightingStyleGeneratorRecipe,
+  serializeLightFixtureGeneratorRecipe,
+  serializeLightingStyleGeneratorRecipe,
+  validateLightFixtureGeneratorRecipe,
+  validateLightingStyleGeneratorRecipe,
+} from './lightingGenerator.js';
+
+export {
+  UNREAL_LIGHTING_MANIFEST_SCHEMA_VERSION,
+  UNREAL_LIGHTING_MANIFEST_TYPE,
+  exportLightingRecipeToUnreal58,
+  serializeUnrealLightingManifest,
+  threePositionToUnreal,
+} from './unrealExport.js';

package/src/lighting/lightDescriptors.js

@@ -0,0 +1,249 @@
+import {
+  createLightColor,
+  createLightIntensity,
+  getDefaultIntensityUnit,
+} from './colorIntensity.js';
+import {
+  clamp,
+  createValidationResult,
+  finite,
+  isPlainObject,
+  mergePlain,
+  slug,
+  vector,
+} from './utils.js';
+
+/** Portable light families supported by the v1 recipe schema. */
+export const LIGHT_TYPES = Object.freeze([
+  'ambient',
+  'hemisphere',
+  'directional',
+  'point',
+  'spot',
+  'rectArea',
+  'discArea',
+  'tubeArea',
+]);
+
+export const SHADOW_CAPABLE_LIGHT_TYPES = Object.freeze(['directional', 'point', 'spot']);
+export const COOKIE_CAPABLE_LIGHT_TYPES = Object.freeze(['spot']);
+
+const DEFAULT_POSITIONS = Object.freeze({
+  ambient: Object.freeze([0, 0, 0]),
+  directional: Object.freeze([8, 12, 6]),
+  discArea: Object.freeze([0, 2, 0]),
+  hemisphere: Object.freeze([0, 1, 0]),
+  point: Object.freeze([0, 2, 0]),
+  rectArea: Object.freeze([0, 2, 0]),
+  spot: Object.freeze([0, 3, 0]),
+  tubeArea: Object.freeze([0, 2, 0]),
+});
+
+const DEFAULT_TARGETS = Object.freeze({
+  ambient: Object.freeze([0, 0, 0]),
+  directional: Object.freeze([0, 0, 0]),
+  discArea: Object.freeze([0, 0, 0]),
+  hemisphere: Object.freeze([0, 0, 0]),
+  point: Object.freeze([0, 0, 0]),
+  rectArea: Object.freeze([0, 0, 0]),
+  spot: Object.freeze([0, 0, 0]),
+  tubeArea: Object.freeze([0, 0, 0]),
+});
+
+function normalizeLayers(value) {
+  const source = Array.isArray(value) ? value : [0];
+  return [...new Set(source.map(Number)
+    .filter((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 31))]
+    .sort((a, b) => a - b);
+}
+
+function normalizeTags(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((entry) => String(entry).trim()).filter(Boolean))];
+}
+
+/** Creates a portable cookie reference. Runtime textures are intentionally not serialized. */
+export function createLightCookie(value = null) {
+  if (!isPlainObject(value)) return null;
+  const uri = String(value.uri ?? value.url ?? '').trim() || null;
+  const key = String(value.key ?? '').trim() || null;
+  if (!uri && !key) return null;
+  return {
+    channel: ['r', 'g', 'b', 'a', 'rgb'].includes(value.channel) ? value.channel : 'rgb',
+    intensity: Math.max(finite(value.intensity, 1), 0),
+    key,
+    uri,
+  };
+}
+
+/** Creates a portable IES photometric-profile reference for host adapters. */
+export function createLightIesProfile(value = null) {
+  if (!isPlainObject(value)) return null;
+  const uri = String(value.uri ?? value.url ?? '').trim() || null;
+  const key = String(value.key ?? '').trim() || null;
+  if (!uri && !key) return null;
+  return {
+    intensity: Math.max(finite(value.intensity, 1), 0),
+    key,
+    uri,
+  };
+}
+
+/** Normalizes portable include/exclude tags used by host light-linking adapters. */
+export function createLightLinking(value = null) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    excludeTags: normalizeTags(source.excludeTags ?? source.exclude),
+    includeTags: normalizeTags(source.includeTags ?? source.include),
+  };
+}
+
+/** Normalizes per-light shadow authoring without allocating a shadow map. */
+export function createLightShadow(value = null, type = 'point') {
+  const source = isPlainObject(value) ? value : {};
+  const supported = SHADOW_CAPABLE_LIGHT_TYPES.includes(type);
+  return {
+    bias: finite(source.bias, -0.0001),
+    enabled: supported && Boolean(source.enabled),
+    extent: Math.max(finite(source.extent, 40), 0.01),
+    far: Math.max(finite(source.far, type === 'directional' ? 250 : 50), 0.01),
+    mapSize: 2 ** Math.round(Math.log2(clamp(finite(source.mapSize, 1024), 128, 8192))),
+    near: Math.max(finite(source.near, 0.1), 0.001),
+    normalBias: Math.max(finite(source.normalBias, 0.01), 0),
+    priority: finite(source.priority, 0),
+    radius: Math.max(finite(source.radius, 1), 0),
+  };
+}
+
+/** Normalizes toon-specific metadata preserved for material adapters. */
+export function createLightArtisticSettings(value = null) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    bandSoftness: clamp(finite(source.bandSoftness, 0.08), 0, 1),
+    diffuseMultiplier: Math.max(finite(source.diffuseMultiplier, 1), 0),
+    rimInfluence: clamp(finite(source.rimInfluence, 0), 0, 1),
+    role: ['key', 'fill', 'rim', 'ambient', 'practical', 'effect'].includes(source.role)
+      ? source.role
+      : 'practical',
+    shadowTint: source.shadowTint === null || source.shadowTint === undefined
+      ? null
+      : createLightColor(source.shadowTint),
+    specularMultiplier: Math.max(finite(source.specularMultiplier, 1), 0),
+  };
+}
+
+/**
+ * Creates a complete JSON-compatible light descriptor.
+ *
+ * @param {string|object} typeOrOptions Light type or an object containing `type`.
+ * @param {object} [options] Partial descriptor when the first argument is a type.
+ */
+export function createLightDescriptor(typeOrOptions = 'point', options = {}) {
+  const source = isPlainObject(typeOrOptions)
+    ? typeOrOptions
+    : isPlainObject(options) ? { ...options, type: typeOrOptions } : { type: typeOrOptions };
+  const type = LIGHT_TYPES.includes(source.type) ? source.type : 'point';
+  const name = String(source.name ?? `${type[0].toUpperCase()}${type.slice(1)} Light`);
+  const id = slug(source.id ?? name, type);
+  const angle = clamp(finite(source.angle, Math.PI / 4), 0.001, Math.PI / 2);
+
+  return {
+    angle,
+    artistic: createLightArtisticSettings(source.artistic),
+    castShadow: SHADOW_CAPABLE_LIGHT_TYPES.includes(type) && Boolean(source.castShadow ?? source.shadow?.enabled),
+    color: createLightColor(source.color),
+    cookie: COOKIE_CAPABLE_LIGHT_TYPES.includes(type) ? createLightCookie(source.cookie) : null,
+    decay: Math.max(finite(source.decay, 2), 0),
+    distance: Math.max(finite(source.distance, 0), 0),
+    enabled: source.enabled === undefined ? true : Boolean(source.enabled),
+    groundColor: createLightColor(source.groundColor ?? [0.18, 0.22, 0.34]),
+    height: Math.max(finite(source.height, 1), 0.001),
+    id,
+    intensity: createLightIntensity(type, source.intensity),
+    ies: ['point', 'spot'].includes(type) ? createLightIesProfile(source.ies) : null,
+    layers: normalizeLayers(source.layers),
+    linking: createLightLinking(source.linking),
+    maxDistance: Math.max(finite(source.maxDistance, source.distance || 0), 0),
+    name,
+    penumbra: clamp(finite(source.penumbra, 0.25), 0, 1),
+    position: vector(source.position, DEFAULT_POSITIONS[type], 3),
+    priority: finite(source.priority, 0),
+    shadow: createLightShadow({ ...source.shadow, enabled: source.castShadow ?? source.shadow?.enabled }, type),
+    tags: normalizeTags(source.tags),
+    target: vector(source.target, DEFAULT_TARGETS[type], 3),
+    type,
+    userData: isPlainObject(source.userData) ? mergePlain({}, source.userData) : {},
+    width: Math.max(finite(source.width, 1), 0.001),
+  };
+}
+
+/** Re-normalizes a descriptor after applying a deep partial update. */
+export function mergeLightDescriptor(descriptor, overrides = {}) {
+  return createLightDescriptor(mergePlain(descriptor, overrides));
+}
+
+export const createAmbientLightDescriptor = (options = {}) => createLightDescriptor('ambient', options);
+export const createHemisphereLightDescriptor = (options = {}) => createLightDescriptor('hemisphere', options);
+export const createDirectionalLightDescriptor = (options = {}) => createLightDescriptor('directional', options);
+export const createPointLightDescriptor = (options = {}) => createLightDescriptor('point', options);
+export const createSpotLightDescriptor = (options = {}) => createLightDescriptor('spot', options);
+export const createRectAreaLightDescriptor = (options = {}) => createLightDescriptor('rectArea', options);
+export const createDiscAreaLightDescriptor = (options = {}) => createLightDescriptor('discArea', options);
+export const createTubeAreaLightDescriptor = (options = {}) => createLightDescriptor('tubeArea', options);
+
+/** Performs structural validation without mutating or coercing the descriptor. */
+export function validateLightDescriptor(value, { path = 'light' } = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!isPlainObject(value)) {
+    errors.push({ message: 'must be an object', path });
+    return createValidationResult(errors, warnings);
+  }
+  if (!LIGHT_TYPES.includes(value.type)) {
+    errors.push({ message: `type must be one of ${LIGHT_TYPES.join(', ')}`, path: `${path}.type` });
+  }
+  if (typeof value.id !== 'string' || !value.id.trim()) {
+    errors.push({ message: 'must be a non-empty string', path: `${path}.id` });
+  }
+  if (value.position !== undefined && (!Array.isArray(value.position)
+    || value.position.length < 3
+    || !value.position.slice(0, 3).every((entry) => Number.isFinite(Number(entry))))) {
+    errors.push({ message: 'must be a finite [x, y, z] array', path: `${path}.position` });
+  }
+  if (value.target !== undefined && (!Array.isArray(value.target)
+    || value.target.length < 3
+    || !value.target.slice(0, 3).every((entry) => Number.isFinite(Number(entry))))) {
+    errors.push({ message: 'must be a finite [x, y, z] array', path: `${path}.target` });
+  }
+  if (value.intensity !== undefined && !isPlainObject(value.intensity) && !Number.isFinite(value.intensity)) {
+    errors.push({ message: 'must be a number or intensity object', path: `${path}.intensity` });
+  }
+  if (isPlainObject(value.intensity)
+    && value.intensity.unit !== undefined
+    && !['unitless', 'lux', 'candela', 'lumens', 'nits'].includes(value.intensity.unit)) {
+    errors.push({ message: 'has an unsupported physical unit', path: `${path}.intensity.unit` });
+  }
+  if (value.cookie && !COOKIE_CAPABLE_LIGHT_TYPES.includes(value.type)) {
+    warnings.push({ message: 'cookies are currently realized only for spot lights', path: `${path}.cookie` });
+  }
+  if (value.ies && !['point', 'spot'].includes(value.type)) {
+    warnings.push({ message: 'IES profiles are portable metadata only for point and spot lights', path: `${path}.ies` });
+  }
+  if (value.linking !== undefined && !isPlainObject(value.linking)) {
+    errors.push({ message: 'must be an include/exclude tag object', path: `${path}.linking` });
+  }
+  if ((value.castShadow || value.shadow?.enabled) && !SHADOW_CAPABLE_LIGHT_TYPES.includes(value.type)) {
+    warnings.push({ message: 'this light type cannot cast Three.js shadows', path: `${path}.shadow` });
+  }
+  const expectedUnit = getDefaultIntensityUnit(value.type);
+  if (isPlainObject(value.intensity)
+    && value.intensity.unit
+    && value.intensity.unit !== expectedUnit
+    && value.intensity.unit !== 'lumens') {
+    warnings.push({
+      message: `${value.intensity.unit} is converted approximately; ${expectedUnit} is native for ${value.type}`,
+      path: `${path}.intensity.unit`,
+    });
+  }
+  return createValidationResult(errors, warnings);
+}

package/src/lighting/lightingCapabilities.js

@@ -0,0 +1,79 @@
+import { LIGHT_TYPES } from './lightDescriptors.js';
+import { cloneJson, finite, isPlainObject } from './utils.js';
+
+function detectBackend(renderer) {
+  if (renderer?.isWebGPURenderer) return 'webgpu';
+  if (renderer?.isWebGLRenderer && renderer.capabilities?.isWebGL2) return 'webgl2';
+  if (renderer?.isWebGLRenderer) return 'webgl1';
+  return 'unknown';
+}
+
+/**
+ * Reports the portable Three.js lighting features available to this module.
+ * This is a capability description, not a GPU benchmark or shader-limit test.
+ */
+export function createLightingCapabilityReport(options = {}) {
+  const source = isPlainObject(options) ? options : {};
+  const renderer = source.renderer ?? null;
+  const backend = source.backend ?? detectBackend(renderer);
+  const maxTextureUnits = Math.max(finite(renderer?.capabilities?.maxTextures, 0), 0);
+  const maxTextureSize = Math.max(finite(renderer?.capabilities?.maxTextureSize, 0), 0);
+  const warnings = [];
+
+  if (backend === 'unknown') warnings.push('No renderer was supplied; runtime capabilities are conservative estimates.');
+  if (backend === 'webgl1') warnings.push('WebGL1 is outside ToonLab lighting v1 support targets.');
+  if (backend === 'webgl2') warnings.push('Large light counts remain shader- and material-dependent on WebGL2; use a measured quality profile.');
+
+  return Object.freeze({
+    backend,
+    features: Object.freeze({
+      areaLights: Object.freeze({
+        discArea: 'rect-area-approximation',
+        rectArea: true,
+        tubeArea: 'rect-area-approximation',
+      }),
+      cookies: Object.freeze({ spot: true }),
+      iesProfiles: 'metadata-only',
+      lightLinking: 'three-layers-plus-metadata',
+      lumen: false,
+      megaLights: false,
+      manyLightRenderer: false,
+      shadows: Object.freeze({
+        ambient: false,
+        directional: true,
+        discArea: false,
+        hemisphere: false,
+        point: true,
+        rectArea: false,
+        spot: true,
+        tubeArea: false,
+      }),
+    }),
+    limits: Object.freeze({
+      maxTextureSize,
+      maxTextureUnits,
+      recipeLightCount: 1024,
+    }),
+    renderer: renderer ? renderer.constructor?.name ?? 'Renderer' : null,
+    supportedLightTypes: LIGHT_TYPES,
+    warnings: Object.freeze(warnings),
+  });
+}
+
+/** Returns one type-specific view of a capability report. */
+export function getLightingTypeCapability(type, report = createLightingCapabilityReport()) {
+  if (!LIGHT_TYPES.includes(type)) return null;
+  const area = report.features.areaLights[type];
+  return {
+    areaRealization: area ?? null,
+    cookies: Boolean(report.features.cookies[type]),
+    iesProfiles: ['point', 'spot'].includes(type) ? report.features.iesProfiles : false,
+    shadows: Boolean(report.features.shadows[type]),
+    type,
+  };
+}
+
+/** Creates a mutable JSON-safe snapshot suitable for logs and diagnostics UIs. */
+export function snapshotLightingCapabilities(report) {
+  return cloneJson(report ?? createLightingCapabilityReport());
+}