Class Light

ReadonlycolorTemperature

Readonlyintensity

Readonlysources

Static ReadonlyZERO

add

• add(other: Light): Light

  Sum two Lights. Lux intensities add. Color temperature blends as the flux-weighted average across all contributing sources; sources whose colorTemperature is null are excluded from the weighting.

  Parameters

  • other: Light

  Returns Light

attenuate

• attenuate(factor: number): Light

  Multiply lux intensity by a 0..1 factor. Sources scale in lockstep so the cap stays accurate.

  Parameters

  • factor: number

  Returns Light

toJSON

• toJSON(): {
      colorTemperature: { unit: "K"; value: number }
      | null;
      intensity: { unit: "lux"; value: number };
      sources: LightSourceRef[];
  }

  JSON serialization shape for tests / debugging.

  Returns {
      colorTemperature: { unit: "K"; value: number } | null;
      intensity: { unit: "lux"; value: number };
      sources: LightSourceRef[];
  }

withColorTemperature

• withColorTemperature(colorTemperature: string | Quantity<"K"> | null): Light

  Return a copy with the color temperature overridden.

  Parameters

  • colorTemperature: string | Quantity<"K"> | null

  Returns Light

StaticapplyBandShift

• applyBandShift(
      band: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding",
      shift: number,
  ): "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"

  Band shift arithmetic delegates to the generic Quantity.shiftTag machinery applied to the lux unit.

  Parameters

  • band: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"
  • shift: number

  Returns "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"

StaticbandFor

• bandFor(
      luxValue: number,
  ): "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"

  Map a lux numeric value to a LightBand. Consults the live Quantity tag-table registry — the lux thresholds live in mud/config/quantity-tags.yaml and load at boot via QuantityApi.loadTagTables. A thin typed adapter over Quantity.tag() for the lux unit; reload of the YAML propagates here transparently.

  Throws if the lux table isn't registered (test setup gap) or if the registered tags don't match LightBand (content-side bug — the YAML tag list must equal the typed union by construction).

  Parameters

  • luxValue: number

  Returns "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"

StaticcoerceColorTemperature

• coerceColorTemperature(
      value: string | Quantity<"K"> | null | undefined,
  ): Quantity<"K"> | null

  Coerce a tag string, a Quantity<'K'>, or null into a Quantity<'K'> | null. Used by Light.of and the mixin setters. String input resolves through the registered KELVIN_TAGS table (in api/light.ts), so author-friendly tags like 'warm' and 'cool' round-trip to their canonical Kelvin values.

  Parameters

  • value: string | Quantity<"K"> | null | undefined

  Returns Quantity<"K"> | null

StaticcompareBand

• compareBand(
      a: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding",
      b: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding",
  ): number

  Band compare arithmetic delegates to the generic Quantity.compareTag machinery applied to the lux unit.

  Parameters

  • a: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"
  • b: "pitch-black" | "very-dim" | "dim" | "lit" | "bright" | "blinding"

  Returns number

Staticfrom

• from(value: LightDataShape | Light): Light

  Coerce a Light | LightDataShape into a Light. Utility for callers holding an externally-sourced plain-object shape and needing a Light instance. NOT part of the persistence path.

  Parameters

  • value: LightDataShape | Light

  Returns Light

Staticof

• of(
      intensity: number | Quantity<"lux">,
      colorTemperature?: string | Quantity<"K"> | null,
      source?: LightSourceRef,
  ): Light

  Public construct-with-defaults helper. Accepts numeric lux or a Quantity<'lux'> for intensity; tag-string, Quantity<'K'>, or null for color temperature.

  Parameters

  • intensity: number | Quantity<"lux">
  • colorTemperature: string | Quantity<"K"> | null = null
  • Optionalsource: LightSourceRef

  Returns Light