@photivra/engine 1.5.0 → 2.0.0

package/docs/api/color-illuminants.md

@@ -0,0 +1,280 @@
+# color/illuminants.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## BOLTZMANN_CONSTANT_JOULES_PER_KELVIN
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+BOLTZMANN_CONSTANT_JOULES_PER_KELVIN = 1.380649e-23
+```
+
+## calculateChromaticityFromCorrelatedColorTemperature
+
+Chromaticity for CCT and Duv: the locus point (Planckian or CIE daylight) offset by
+Duv along the unit normal of the Planckian locus at the same temperature in the CIE
+1960 UCS. For `cie-daylight`, Duv = 0 returns the daylight-locus point itself.
+Throws InvalidScientificInputError when the offset point is not a physical chromaticity
+(x ≥ 0, y > 0, x + y ≤ 1), for example 2000 K with Duv +0.02 (x + y ≈ 1.06).
+
+```ts
+export function calculateChromaticityFromCorrelatedColorTemperature(input: {
+  correlatedColorTemperatureKelvin: number;
+  duv: number;
+  whiteLocus: WhiteLocus;
+  locus: PlanckianLocusModel;
+}): CalculationResult<CieXyChromaticity>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateCieDaylightComponentWeights
+
+CIE daylight-locus chromaticity and S₁/S₂ weights for a CCT in 4000–25000 K
+(CIE 15:2018 §4.1.2, paid; no free text of the formulas found). M₁, M₂ rounded to three decimals
+reproduce the free CIE D55 and D65 tables (DOI 10.25039/CIE.DS.qewfb3kp, 10.25039/CIE.DS.hjfjmt59)
+to their rounding; `coefficientRounding` makes that rounding explicit.
+The temperature is used as given: D65's nominal 6500 K corresponds to 6504 K here.
+
+```ts
+export function calculateCieDaylightComponentWeights(input: {
+  correlatedColorTemperatureKelvin: number;
+  coefficientRounding: "none" | "cie-three-decimals";
+}): CalculationResult<CieDaylightComponentWeights>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateCieIlluminantARelativeSpectralPower
+
+CIE standard illuminant A relative SPD from its defining formula (100 at 560 nm),
+with c₂ = 1.435e-2 m·K and T = 2848 K as in the standard (≈ 2856 K with the
+current c₂). Valid 300–830 nm.
+
+```ts
+export function calculateCieIlluminantARelativeSpectralPower(wavelengthNanometers: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateCorrelatedColorTemperature
+
+CCT and Duv of a chromaticity as the nearest point of the Planckian locus in the CIE
+1960 UCS (Smet et al. 2023; also CIE 15:2018). Finds the root of the analytic temperature derivative
+of the squared uv distance (safeguarded Newton with bisection fallback, bracketed by a cached coarse
+scan in reciprocal temperature), converged until a step changes T by at most 1e-10 of T. Throws
+(fails closed) when the nearest point lies beyond the model's range, or when |Duv| > 0.05 (see
+{@link MAX_CORRELATED_COLOR_TEMPERATURE_DUV}). Duv is positive above the locus (toward green) and
+negative below it, the engine's documented sign convention.
+
+```ts
+export function calculateCorrelatedColorTemperature(input: { chromaticity: CieXyChromaticity; locus: PlanckianLocusModel }): CalculationResult<CorrelatedColorTemperatureResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculatePlanckianChromaticity
+
+Planckian chromaticity at T using either locus model.
+
+```ts
+export function calculatePlanckianChromaticity(input: { temperatureKelvin: number; locus: PlanckianLocusModel }): CalculationResult<CieXyChromaticity>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculatePlanckianSpectralRadiance
+
+Planck's law for blackbody spectral radiance per unit (vacuum) wavelength:
+L(λ, T) = 2hc² / λ⁵ / (exp(hc/(λkT)) − 1). Returns W·m⁻²·sr⁻¹·nm⁻¹.
+
+```ts
+export function calculatePlanckianSpectralRadiance(input: { temperatureKelvin: number; wavelengthNanometers: number }): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CIE_DAYLIGHT_LOCUS_RANGE_KELVIN
+
+CIE daylight-locus validity, K.
+
+```ts
+CIE_DAYLIGHT_LOCUS_RANGE_KELVIN = Object.freeze({ minimum: 4000, maximum: 25000 })
+```
+
+## CIE_ILLUMINANT_A_RANGE_NANOMETERS
+
+CIE illuminant A defining range (nm).
+
+```ts
+CIE_ILLUMINANT_A_RANGE_NANOMETERS = Object.freeze({ minimum: 300, maximum: 830 })
+```
+
+## CieDaylightBasis
+
+Caller-supplied CIE daylight basis S₀, S₁, S₂ (tabulated; CIE dataset not bundled).
+
+```ts
+export interface CieDaylightBasis {
+  s0: readonly ColorimetricSpectralSample[];
+  s1: readonly ColorimetricSpectralSample[];
+  s2: readonly ColorimetricSpectralSample[];
+  /** Caller identity of the basis dataset (for example a DOI). */
+  datasetId: string;
+}
+```
+
+## CieDaylightComponentWeights
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CieDaylightComponentWeights {
+  correlatedColorTemperatureKelvin: number;
+  chromaticity: CieXyChromaticity;
+  m1: number;
+  m2: number;
+  coefficientRounding: "none" | "cie-three-decimals";
+}
+```
+
+## CorrelatedColorTemperatureResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CorrelatedColorTemperatureResult {
+  correlatedColorTemperatureKelvin: number;
+  /** Signed CIE 1960 uv distance from the locus; positive above (greenish), negative below (the engine's convention). */
+  duv: number;
+}
+```
+
+## createCieDaylightSpectrum
+
+Builds a CIE D-series relative SPD S(λ) = S₀ + M₁S₁ + M₂S₂ on the S₀ wavelengths from
+caller-supplied basis tables (S₁, S₂ linearly interpolated; fail closed outside range).
+
+```ts
+export function createCieDaylightSpectrum(input: {
+  correlatedColorTemperatureKelvin: number;
+  coefficientRounding: "none" | "cie-three-decimals";
+  basis: CieDaylightBasis;
+}): ColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createCieIlluminantASpectrum
+
+CIE illuminant A as a function spectrum over its defining range.
+
+```ts
+export function createCieIlluminantASpectrum(): ColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createPlanckianSpectrum
+
+Planckian spectral radiance (W·m⁻²·sr⁻¹·nm⁻¹) as a function spectrum over the given range.
+
+```ts
+export function createPlanckianSpectrum(input: { temperatureKelvin: number; wavelengthRangeNanometers: SpectralWavelengthRangeNanometers }): ColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## estimateCorrelatedColorTemperatureMcCamy
+
+McCamy (1992) cubic estimate of CCT from CIE 1931 xy:
+n = (x − 0.3320)/(0.1858 − y), CCT = 449 n³ + 3525 n² + 6823.3 n + 5520.33.
+An approximation that carries no Duv. Measured for this engine (October 17, 2026) on points of a
+Planckian locus integrated from the CIE 1931 2° 1 nm table (360–830 nm, exact c₂): it deviates by up
+to 10 K over 2856–6504 K (largest near 3500 K), 19 K at 2000 K, 17 K at 8000 K, 118 K at 10000 K
+and 442 K at 12500 K. See docs/COLORIMETRY.md.
+
+```ts
+export function estimateCorrelatedColorTemperatureMcCamy(input: { chromaticity: CieXyChromaticity }): CalculationResult<{ correlatedColorTemperatureKelvin: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## estimatePlanckianLocusChromaticity
+
+Planckian-locus chromaticity at T (1000–100000 K): Planck's law integrated against the engine's
+analytic CIE 1931 CMFs with 1 nm nodes from 360 to 830 nm. An approximation, because the CMFs are
+an analytic fit; with tabulated CMFs use {@link calculatePlanckianChromaticity}.
+
+```ts
+export function estimatePlanckianLocusChromaticity(input: { temperatureKelvin: number }): CalculationResult<CieXyChromaticity>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## MAX_CORRELATED_COLOR_TEMPERATURE_DUV
+
+Engine limit: no CCT beyond |Duv| = 0.05, the range over which Smet et al. (2023, free) evaluate CCT
+methods for nominally white light (CIE 15:2018 §9.5, paid, gives the same limit).
+
+```ts
+MAX_CORRELATED_COLOR_TEMPERATURE_DUV = 0.05
+```
+
+## PLANCK_CONSTANT_JOULE_SECONDS
+
+Exact SI defining constants (BIPM SI Brochure, 9th edition, 2019).
+
+```ts
+PLANCK_CONSTANT_JOULE_SECONDS = 6.62607015e-34
+```
+
+## PLANCKIAN_LOCUS_RANGE_KELVIN
+
+Temperature range of the Planckian-locus models, K.
+
+```ts
+PLANCKIAN_LOCUS_RANGE_KELVIN = Object.freeze({ minimum: 1000, maximum: 100000 })
+```
+
+## PlanckianLocusModel
+
+Selects how the Planckian locus is evaluated.
+
+```ts
+export type PlanckianLocusModel =
+  | {
+      /** Planck's law integrated against the engine's analytic CIE 1931 CMFs, 1 nm nodes 360–830 nm (the default). */
+      kind: "planck-analytic-cmf";
+    }
+  | {
+      kind: "planck-integration";
+      colorMatchingFunctions: ColorMatchingFunctionsSource;
+      quadratureNodes: readonly ColorimetricQuadratureNode[];
+    };
+```
+
+## SECOND_RADIATION_CONSTANT_METER_KELVIN
+
+Second radiation constant c₂ = hc/k in m·K (derived from the exact constants).
+
+```ts
+SECOND_RADIATION_CONSTANT_METER_KELVIN = (PLANCK_CONSTANT_JOULE_SECONDS * SPEED_OF_LIGHT_METERS_PER_SECOND) / BOLTZMANN_CONSTANT_JOULES_PER_KELVIN
+```
+
+## SPEED_OF_LIGHT_METERS_PER_SECOND
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SPEED_OF_LIGHT_METERS_PER_SECOND = 299_792_458
+```
+
+## WhiteLocus
+
+Locus whose temperature defines a white for CCT + Duv.
+
+```ts
+export type WhiteLocus = "planckian" | "cie-daylight";
+```

package/docs/api/color-rgb-color-spaces.md

@@ -0,0 +1,151 @@
+# color/rgb-color-spaces.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## Bt1886Eotf
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface Bt1886Eotf {
+  whiteLuminanceCdPerSquareMeter: number;
+  blackLuminanceCdPerSquareMeter: number;
+  /** a = (Lw^(1/γ) − Lb^(1/γ))^γ */
+  a: number;
+  /** b = Lb^(1/γ) / (Lw^(1/γ) − Lb^(1/γ)) */
+  b: number;
+  /** L = a · max(V + b, 0)^2.4 in cd/m². */
+  decode(signal: number): number;
+  /** Inverse: V = (L/a)^(1/2.4) − b. */
+  encode(luminanceCdPerSquareMeter: number): number;
+}
+```
+
+## calculateRgbToXyzMatrices
+
+Derives RGB ↔ XYZ matrices from primaries and white chromaticity: columns are the primaries'
+XYZ (Y = 1) scaled so that RGB (1, 1, 1) maps to the white (W3C CSS Color 4, free; also SMPTE
+RP 177). The derivation is written out in docs/COLORIMETRY.md.
+
+```ts
+export function calculateRgbToXyzMatrices(input: { primaries: RgbPrimaryChromaticities; whiteChromaticity: CieXyChromaticity }): CalculationResult<RgbToXyzMatrices>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## evaluateBt709InverseOetf
+
+Inverse of the BT.709 OETF: L = V/4.5 for V < 0.081, otherwise ((V + 0.099)/1.099)^(1/0.45).
+
+```ts
+export function evaluateBt709InverseOetf(encoded: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## evaluateBt709Oetf
+
+ITU-R BT.709-6 / BT.2020-2 (10-bit) OETF: V = 4.5 L for L < 0.018, otherwise
+1.099 L^0.45 − 0.099. Scene-referred camera encoding, not a display EOTF.
+
+```ts
+export function evaluateBt709Oetf(sceneLinear: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## evaluateSrgbDecoding
+
+sRGB / Display P3 decoding of one non-linear component.
+
+```ts
+export function evaluateSrgbDecoding(encoded: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## evaluateSrgbEncoding
+
+sRGB / Display P3 encoding (W3C CSS Color 4; also IEC 61966-2-1) of one linear component; negative values use the linear segment.
+
+```ts
+export function evaluateSrgbEncoding(linear: number): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## prepareBt1886Eotf
+
+Prepares the ITU-R BT.1886 reference EOTF (γ = 2.4) for a display's white and black luminance.
+
+```ts
+export function prepareBt1886Eotf(input: { whiteLuminanceCdPerSquareMeter: number; blackLuminanceCdPerSquareMeter: number }): Bt1886Eotf;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveRgbColorSpace
+
+Resolves a named RGB colour space with numerically derived matrices (all D65).
+
+```ts
+export function resolveRgbColorSpace(id: RgbColorSpaceId): CalculationResult<RgbColorSpaceDefinition>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RgbColorSpaceDefinition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RgbColorSpaceDefinition extends RgbToXyzMatrices {
+  id: RgbColorSpaceId;
+  primaries: RgbPrimaryChromaticities;
+  whiteChromaticity: CieXyChromaticity;
+  /** Conventional non-linear (SDR) encoding of this space. */
+  transferFunction: RgbTransferFunctionId;
+  sources: readonly string[];
+}
+```
+
+## RgbColorSpaceId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type RgbColorSpaceId = "srgb" | "display-p3" | "rec709" | "rec2020";
+```
+
+## RgbPrimaryChromaticities
+
+RGB primaries as CIE 1931 xy chromaticities.
+
+```ts
+export interface RgbPrimaryChromaticities {
+  red: CieXyChromaticity;
+  green: CieXyChromaticity;
+  blue: CieXyChromaticity;
+}
+```
+
+## RgbToXyzMatrices
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RgbToXyzMatrices {
+  /** Linear RGB (white = 1, 1, 1) → XYZ with white Y = 1. */
+  rgbToXyz: ColorMatrix3x3;
+  xyzToRgb: ColorMatrix3x3;
+  whiteXyz: CieXyzTristimulus;
+}
+```
+
+## RgbTransferFunctionId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type RgbTransferFunctionId = "srgb" | "bt709-oetf-bt1886-eotf" | "bt2020-oetf";
+```

package/docs/api/color-sensor-color-development.md

@@ -0,0 +1,27 @@
+# color/sensor-color-development.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## RAW_HIGHLIGHT_RECONSTRUCTION_START
+
+Normalized channel level where `reconstruct` starts blending toward neutral.
+
+```ts
+RAW_HIGHLIGHT_RECONSTRUCTION_START = 0.8
+```
+
+## RawHighlightMode
+
+RAW development highlight policy; see the module notes.
+
+```ts
+export type RawHighlightMode = "clip" | "reconstruct";
+```
+
+## SENSOR_COLOR_DEVELOPMENT_MODEL
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_COLOR_DEVELOPMENT_MODEL = Object.freeze({ id: "sensor-color-development", version: "2.0.0" } as const)
+```

package/docs/api/color-srgb-icc.md

@@ -1,12 +1,10 @@
 # color/srgb-icc.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## createSrgbIccProfile
 
-Reference: https://registry.color.org/rgb-registry/files/sRGB.pdf and ICC.1:2022.
-This is an original Photivra profile, not a redistributed ICC or operating-system profile.
-Bradford here encodes the D50 profile-connection space; it does not apply shooting WB.
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
 export function createSrgbIccProfile():Uint8Array;

package/docs/api/color-white-balance.md

@@ -1,6 +1,6 @@
 # color/white-balance.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION
 
@@ -11,6 +11,19 @@ COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION =
   "0.1.0" as const
 ```
 
+## ColorTemperatureWhiteBalanceCameraModel
+
+Camera colour model used to turn a declared white into channel gains.
+
+```ts
+export interface ColorTemperatureWhiteBalanceCameraModel {
+  profileId: string;
+  profileVersion: string;
+  /** Row-major CIE XYZ (white Y = 1) → relative pre-WB camera-linear RGB. */
+  xyzToCameraRgb: ColorMatrix3x3;
+}
+```
+
 ## ColorTemperatureWhiteBalanceIntent
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -31,8 +44,9 @@ export interface ColorTemperatureWhiteBalanceIntent {
 
 Records independent color-temperature and tint intent.
 
-No channel gains are fabricated here; mapping CCT+tint into a camera's
-channel/color space belongs to a profile/colorimetry contract.
+No channel gains are fabricated here; use
+`resolveColorTemperatureWhiteBalance()` with an explicit camera colour model to
+resolve gains.
 
 ```ts
 export function createColorTemperatureWhiteBalanceIntent(
@@ -58,8 +72,8 @@ export interface CreateColorTemperatureWhiteBalanceIntentInput {
 
 Freezes a resolved WB state under a new stable identity.
 
-Locking changes neither the scene nor the gains; later AWB estimates may
-differ while this locked state remains unchanged.
+Locking changes neither the scene nor the gains. Later AWB estimates may
+differ, but this locked state stays the same.
 
 ```ts
 export function createLockedWhiteBalanceState(
@@ -84,9 +98,10 @@ export interface CreateLockedWhiteBalanceStateInput {
 
 Estimates one global AWB state from declared pre-WB camera-linear samples.
 
-It intentionally does not accept true illuminant metadata. A gray-world
-neutralizing estimate is softened by the profile's correctionStrength so
-different generic AWB priorities can preserve different amounts of cast.
+It deliberately does not accept metadata about the true illuminant. A
+grey-world neutralizing estimate is softened by the profile's
+correctionStrength, so different generic AWB priorities can keep different
+amounts of colour cast.
 
 ```ts
 export function estimateAutoWhiteBalance(
@@ -111,11 +126,12 @@ export interface EstimateAutoWhiteBalanceInput {
 
 ## parseResolvedWhiteBalanceState
 
-Parses a committed resolved white-balance state from an untrusted JSON
-boundary without re-estimating WB.
+Parses a committed, resolved white-balance state from untrusted JSON,
+without estimating WB again.
 
-This is intentionally a state parser, not an AWB estimator. It preserves the
-resolved gains/policy/measurement identity that a capture committed earlier.
+This is deliberately a state parser, not an AWB estimator. It keeps the
+resolved gains, policy and measurement identity that a capture committed
+earlier.
 
 ```ts
 export function parseResolvedWhiteBalanceState(
@@ -129,8 +145,8 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 Parses generic WB presets and AWB policies.
 
-Preset gains and AWB correction strength are profile-owned. Labels are not
-treated as universal Kelvin aliases or manufacturer-specific behavior.
+The profile defines preset gains and AWB correction strength. A label is not
+treated as a universal Kelvin value or as any manufacturer's behaviour.
 
 ```ts
 export function parseWhiteBalanceProfile(
@@ -167,6 +183,44 @@ export interface PreWhiteBalanceRgbSampleSet {
 }
 ```
 
+## resolveColorTemperatureWhiteBalance
+
+Resolves a Kelvin + tint WB intent into camera channel gains, for an explicit camera
+colour model:
+- white xy = locus(CCT), offset by Duv = tint along the Planckian-locus normal in CIE 1960 uv;
+- camera neutral n = M_XYZ→camera · XYZ(white, Y = 1);
+- gains = (n_G/n_R, 1, n_G/n_B).
+A neutral surface lit by light of exactly that chromaticity then renders with equal channels.
+The CCT and tint are the white the photographer declares, not a measured scene illuminant.
+Accuracy is limited by the camera matrix (exact only under the Luther–Ives condition) and by
+the locus model.
+
+```ts
+export function resolveColorTemperatureWhiteBalance(
+  input: ResolveColorTemperatureWhiteBalanceInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveColorTemperatureWhiteBalanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveColorTemperatureWhiteBalanceInput {
+  stateId: string;
+  intent: ColorTemperatureWhiteBalanceIntent;
+  /** Locus whose temperature defines the white: Planckian or CIE daylight. */
+  whiteLocus: WhiteLocus;
+  /** Tint is read as Duv in the CIE 1960 UCS (positive = above the Planckian locus, greenish). */
+  tintInterpretation: "duv-cie-1960-uv";
+  /** Defaults to Planck's law integrated against the engine's analytic CIE 1931 CMFs (`planck-analytic-cmf`). */
+  planckianLocus?: PlanckianLocusModel;
+  camera: ColorTemperatureWhiteBalanceCameraModel;
+}
+```
+
 ## resolveCustomWhiteBalance
 
 Resolves a user-declared neutral/gray custom-WB measurement.
@@ -193,6 +247,25 @@ export interface ResolveCustomWhiteBalanceInput {
 }
 ```
 
+## ResolvedColorTemperatureWhiteBalance
+
+Locus/tint interpretation and camera neutral behind a Kelvin + tint WB state.
+
+```ts
+export interface ResolvedColorTemperatureWhiteBalance {
+  intentId: string;
+  colorTemperatureKelvin: number;
+  tint: number;
+  whiteLocus: WhiteLocus;
+  tintInterpretation: "duv-cie-1960-uv";
+  planckianLocusModel: "planck-analytic-cmf" | "planck-integration";
+  /** CIE 1931 xy of the declared white (CCT + Duv). */
+  adoptedWhiteChromaticity: CieXyChromaticity;
+  /** Pre-WB camera response to that white (XYZ with Y = 1 through xyzToCameraRgb). */
+  cameraNeutralRgb: WhiteBalanceChannelGains;
+}
+```
+
 ## ResolvedWhiteBalanceState
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -206,7 +279,8 @@ export interface ResolvedWhiteBalanceState {
     | "preset"
     | "manual-gains"
     | "custom-measurement"
-    | "auto-white-balance";
+    | "auto-white-balance"
+    | "color-temperature";
   channelGains: WhiteBalanceChannelGains;
   locked: boolean;
   sourceProfile?: {
@@ -229,6 +303,8 @@ export interface ResolvedWhiteBalanceState {
       blue: number;
     };
   };
+  /** Present for `color-temperature` states: the declared CCT/tint and its camera neutral. */
+  colorTemperature?: ResolvedColorTemperatureWhiteBalance;
   sourceStateId?: string;
   trueIlluminantMetadataUsed: false;
   sceneIlluminationModified: false;
@@ -264,7 +340,7 @@ export interface ResolveManualWhiteBalanceInput {
 
 ## resolvePresetWhiteBalance
 
-Resolves a profile-owned WB preset without universal label/Kelvin rules.
+Resolves a WB preset defined by the profile. No universal label-to-Kelvin rule is applied.
 
 ```ts
 export function resolvePresetWhiteBalance(
@@ -322,9 +398,9 @@ export interface WhiteBalanceAwbPolicy {
   policyId: string;
   intent: WhiteBalanceAwbIntent;
   /**
-   * Fraction of a gray-world neutralizing correction applied in logarithmic
-   * gain space. 1 is full neutral-priority correction; lower values preserve
-   * more of the observed cast.
+   * How much of a grey-world neutralizing correction to apply, measured in
+   * logarithmic gain space. 1 applies the full correction (neutral priority).
+   * Lower values keep more of the observed colour cast.
    */
   correctionStrength: EvidenceBackedFact<number>;
   limitations?: readonly string[];