@photivra/engine 1.5.0 → 2.1.0

package/docs/api/optics-profile-contract.md

@@ -1,10 +1,10 @@
 # optics/profile-contract.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.
 
 ## GenericOpticalEvidence
 
-Generic approximation evidence; never implies measured calibration.
+Evidence for a generic approximation. It never implies a measured calibration.
 
 ```ts
 export interface GenericOpticalEvidence {
@@ -17,7 +17,7 @@ export interface GenericOpticalEvidence {
 
 ## OpticalProfileState
 
-Exact, generic camera/lens and acquisition state; no implicit interpolation.
+Exact, generic camera, lens and acquisition state. Nothing is interpolated implicitly.
 
 ```ts
 export interface OpticalProfileState {
@@ -38,7 +38,7 @@ export interface OpticalProfileState {
 
 ## parseOpticalProfileState
 
-Parses a complete exact-state binding, including still/video/output settings.
+Parses a complete exact-state binding, including still, video and output settings.
 
 ```ts
 export function parseOpticalProfileState(value: unknown): OpticalProfileState;

package/docs/api/optics-psf-foundation.md

@@ -1,17 +1,16 @@
 # optics/psf-foundation.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.
 
 ## calculatePsfFoundationComponents
 
-Evaluates the currently implemented PSF-related diagnostics in one explicit
-field/depth/spectral/pupil context without combining them into a synthetic
-PSF or blur radius.
+Evaluates today's PSF-related diagnostics in one explicit context (field
+position, depth, wavelength and pupil). It does not combine them into a
+synthetic PSF or blur radius.
 
-Field position is recorded even though the current defocus-circle and
-circular-Airy diagnostics are not field dependent. Future field-dependent
-contributions can consume the same context without changing these existing
-primitives.
+The field position is recorded even though the current defocus-circle and
+circular-Airy diagnostics do not depend on it. Future field-dependent
+contributions can use the same context without changing these primitives.
 
 ```ts
 export function calculatePsfFoundationComponents(
@@ -37,8 +36,9 @@ export interface CalculatePsfFoundationComponentsInput {
    */
   fieldPointMm: LensFieldPointMm;
   /**
-   * Physical image-plane radius used only to normalize field position for
-   * cross-case diagnostics. It is not a lens calibration or validity bound.
+   * Physical image-plane radius. It is used only to normalize the field
+   * position so diagnostics can be compared across cases. It is not a lens
+   * calibration or a validity limit.
    */
   fieldNormalizationRadiusMm: number;
   spectralBasis: {
@@ -52,8 +52,8 @@ export interface CalculatePsfFoundationComponentsInput {
 
 Returns the public PSF/pupil foundation contract.
 
-The contract describes current diagnostics plus reserved future contribution
-ownership. It does not imply that reserved contributions are implemented.
+The contract lists today's diagnostics and reserves names for future
+contributions. A reserved contribution is not implemented.
 
 ```ts
 export function getPsfFoundationContract(): PsfFoundationContract;

package/docs/api/optics-pupil-vignetting.md

@@ -0,0 +1,132 @@
+# optics/pupil-vignetting.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.
+
+## calculateMechanicalVignetting
+
+Mechanical vignetting at one field angle: the open (cat's-eye) pupil from intersecting the
+entrance pupil with displaced clipping apertures, its area ratio, and cos^4 x area ratio.
+
+```ts
+export function calculateMechanicalVignetting(
+  input: CalculateMechanicalVignettingInput
+): CalculationResult<MechanicalVignetting>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateMechanicalVignettingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateMechanicalVignettingInput {
+  /** Unclipped entrance-pupil diameter, mm. */
+  entrancePupilDiameterMm: number;
+  /** Object-space field angle from the optical axis, degrees, in [0, 90). */
+  fieldAngleDegrees: number;
+  /** Image-plane direction of the field point, degrees counter-clockwise from +X. */
+  fieldAzimuthDegrees: number;
+  /** One through eight clipping apertures. */
+  apertures: readonly MechanicalVignettingAperture[];
+  /** Boundary samples per circle for the polygon, from 16 to 4096 (default 256). */
+  boundarySamplesPerCircle?: number;
+}
+```
+
+## calculateNaturalVignetting
+
+Natural (cos^4 or finite Lambertian pupil) relative illumination at one image point.
+
+```ts
+export function calculateNaturalVignetting(
+  input: CalculateNaturalVignettingInput
+): CalculationResult<NaturalVignetting>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateNaturalVignettingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateNaturalVignettingInput {
+  model: NaturalVignettingModel;
+  /** Image-plane point relative to the optical axis, mm. */
+  imagePointMm: { x: number; y: number };
+  /** Axial distance from the exit pupil to the image plane, mm. */
+  exitPupilDistanceMm: number;
+  /** Exit-pupil diameter, mm; required for finite-lambertian-pupil. */
+  exitPupilDiameterMm?: number;
+}
+```
+
+## MechanicalVignetting
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MechanicalVignetting {
+  fieldAngleDegrees: number;
+  fieldAzimuthDegrees: number;
+  entrancePupilAreaSquareMm: number;
+  /** Open area in mm^2. Exact for a single aperture; the polygon area otherwise. */
+  openAreaSquareMm: number;
+  areaMethod: "exact-circle-circle-intersection" | "boundary-polygon";
+  /** Open area / unclipped pupil area, in [0, 1]. */
+  openAreaRatio: number;
+  /** cos^4(field angle). */
+  cosineFourthFactor: number;
+  /** cos^4(theta) x openAreaRatio. */
+  combinedRelativeIllumination: number;
+  /** Counter-clockwise convex boundary of the open pupil (empty when fully vignetted), mm. */
+  openPupilPolygonMm: readonly { x: number; y: number }[];
+  /** Area centroid of the boundary polygon, mm (null when fully vignetted). */
+  openPupilCentroidMm: { x: number; y: number } | null;
+}
+```
+
+## MechanicalVignettingAperture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MechanicalVignettingAperture {
+  /** Aperture radius referred to the entrance-pupil plane, mm. */
+  radiusMm: number;
+  /**
+   * Signed shift of the aperture's projected centre per unit tan(field angle), in mm, along the
+   * field azimuth. Positive means toward the field point.
+   */
+  shiftPerTanFieldMm: number;
+}
+```
+
+## NaturalVignetting
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NaturalVignetting {
+  model: NaturalVignettingModel;
+  /** Image-space chief-ray angle, radians. */
+  chiefRayAngleRadians: number;
+  /** Relative illumination E / E(axis), in (0, 1]. */
+  relativeIllumination: number;
+  /** Positive exposure loss, stops. */
+  attenuationStops: number;
+  /** cos^4 of the chief-ray angle, reported for comparison. */
+  cosineFourthFactor: number;
+}
+```
+
+## NaturalVignettingModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NaturalVignettingModel =
+  | "cosine-fourth"
+  | "finite-lambertian-pupil";
+```

package/docs/api/optics-radial-distortion.md

@@ -1,11 +1,11 @@
 # optics/radial-distortion.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.
 
 ## calculateInverseRadialDistortionMapping
 
-Invert the declared monotonic radial field map within its supported envelope using the existing
-bounded root solve and preserve explicit optical coordinates.
+Inverts the declared monotonic radial field mapping inside its supported range, using the existing
+bounded root solver. Optical coordinates are kept explicit.
 
 ```ts
 export function calculateInverseRadialDistortionMapping(
@@ -29,11 +29,11 @@ export interface CalculateInverseRadialDistortionMappingInput {
 
 ## calculateInverseRadialDistortionMappings
 
-Inverse-maps multiple distorted image-plane destinations while validating
-and resolving the radial profile only once for the complete batch.
+Inverse-maps many distorted image-plane points at once. The radial profile
+is validated and resolved only once for the whole batch.
 
-The returned per-point mappings are numerically identical to the scalar API;
-provenance and profile validation are shared once at the batch boundary.
+Each returned mapping is numerically identical to the single-point API.
+Provenance and profile validation are reported once for the batch.
 
 ```ts
 export function calculateInverseRadialDistortionMappings(
@@ -66,9 +66,9 @@ The mapping is rotationally symmetric about the optical axis:
 
 where r is normalized by the caller-declared physical reference radius.
 
-The profile is accepted only when the radial mapping is strictly monotonic
-over its declared operating radius, which makes inverse destination-to-source
-sampling well-defined.
+A profile is accepted only if the radial mapping is strictly monotonic over
+its declared operating radius. That makes the inverse mapping
+(destination-to-source sampling) well defined.
 
 ```ts
 export function calculateRadialDistortionMapping(
@@ -185,8 +185,8 @@ export interface RadialDistortionProfile {
    */
   normalizationRadiusMm: number;
   /**
-   * Maximum undistorted normalized radius over which this profile is declared
-   * valid and must remain one-to-one/invertible.
+   * Largest undistorted normalized radius for which this profile is declared
+   * valid. Within it the mapping must stay one-to-one and invertible.
    */
   maximumNormalizedRadius: number;
   coefficients: RadialDistortionCoefficients;

package/docs/api/optics-scene-to-sensor-irradiance.md

@@ -1,16 +1,20 @@
 # optics/scene-to-sensor-irradiance.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.
 
 ## calculateSceneRadianceToSensorIrradiance
 
-Apply declared pupil acceptance and exactly one transmission/field-throughput path to spectral scene
-radiance, returning pre-stack irradiance with conservative evidence.
+Applies the declared pupil acceptance and exactly one transmission or field-throughput path to
+spectral scene radiance. Returns the irradiance before the sensor stack, with conservative
+evidence.
 
-The optical bridge maps outgoing W/m²/sr/nm radiance to pre-sensor-stack W/m²/nm irradiance.
-Circular paraxial acceptance is pi/(4*Nworking²); finite-focus unity-pupil geometry uses N*(1+m).
-Spectral transmission and effective working T-stop are alternative paths, and field throughput is
-applied exactly once. Sensor response and PSF redistribution are downstream.
+The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
+at the front of the sensor stack.
+- Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
+  the working f-number is N*(1+m).
+- Spectral transmission and an effective working T-stop are alternative paths; use one.
+- Field throughput is applied exactly once.
+- Sensor response and PSF (point-spread function) blur happen later in the pipeline.
 
 ```ts
 export function calculateSceneRadianceToSensorIrradiance(
@@ -196,13 +200,16 @@ export type OpticalTransmissionModel =
 
 ## parseSceneToSensorIrradianceProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted scene-to-sensor profile and returns the normalized typed contract. Unknown
+enum values, missing required fields and incompatible scientific data are rejected here.
 
-The optical bridge maps outgoing W/m²/sr/nm radiance to pre-sensor-stack W/m²/nm irradiance.
-Circular paraxial acceptance is pi/(4*Nworking²); finite-focus unity-pupil geometry uses N*(1+m).
-Spectral transmission and effective working T-stop are alternative paths, and field throughput is
-applied exactly once. Sensor response and PSF redistribution are downstream.
+The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
+at the front of the sensor stack.
+- Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
+  the working f-number is N*(1+m).
+- Spectral transmission and an effective working T-stop are alternative paths; use one.
+- Field throughput is applied exactly once.
+- Sensor response and PSF (point-spread function) blur happen later in the pipeline.
 
 ```ts
 export function parseSceneToSensorIrradianceProfile(
@@ -309,8 +316,12 @@ export interface SceneToSensorIrradianceResult {
     number;
   frontOfLensFilterTransmissionAppliedExactlyOnce:
     true;
+  /**
+   * True when a front-of-lens linear polarizer was applied. Scene radiance is unpolarized in this
+   * bridge, so a polarizer transmits (k1 + k2) / 2.
+   */
   frontOfLensFilterPolarizationModeled:
-    false;
+    boolean;
   fieldThroughputFactor: number;
   effectiveAcceptanceAfterTransmissionAndFieldSteradians:
     number;

package/docs/api/optics-scene-to-sensor-quadrature.md

@@ -1,13 +1,15 @@
 # optics/scene-to-sensor-quadrature.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.
 
 ## calculateSceneToSensorIrradianceQuadrature
 
-Calculate the existing paraxial optical bridge at every requested node.
-Exact identity/coverage and provider bindings are checked before returning
-physical W/m²/nm samples. Image coordinates belong to the spatial plan, so
-callers cannot attach a field-throughput result from a different point.
+Runs the existing paraxial optical bridge at every requested node.
+
+Before it returns physical W/m²/nm samples, it checks that node identities,
+grid coverage and provider bindings match exactly. Image coordinates come
+from the spatial plan, so a caller cannot attach a field-throughput result
+computed at a different point.
 
 ```ts
 export function calculateSceneToSensorIrradianceQuadrature(
@@ -19,27 +21,28 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CalculateSceneToSensorIrradianceQuadratureInput
 
-Static point-sample bridge; PSF and temporal transport remain separate responsibilities.
+Static point-sample bridge. PSF blur and motion over time are handled elsewhere.
 
 ```ts
 export interface CalculateSceneToSensorIrradianceQuadratureInput {
   spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
   spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
-  /** Evidence-backed provider/illumination/material identities, parsed before use. */
+  /** Provider, illumination and material identities with their evidence. Parsed before use. */
   sceneBindings: Omit<ValidateSceneRadianceEvaluationBindingsInput, "request" | "result">;
   /** One declared lens/focus/filter state shared by every node. */
   optics: Omit<CalculateSceneRadianceToSensorIrradianceInput,
     "sceneRadianceRequest" | "sceneRadianceResult" | "imagePointMm" | "fieldThroughput">;
-  /** Explicit nonnegative instant shared by all queries; not an exposure integration. */
+  /** One non-negative instant shared by all queries. This is not an integral over the exposure. */
   timeSecondsFromExposureStart: number;
-  /** Complete Cartesian coverage with a unique scene sampleId per node. */
+  /** Every combination of the grid axes, with a unique scene sampleId per node. */
   samples: readonly SceneSensorQuadratureSample[];
 }
 ```
 
 ## SceneSensorQuadratureSample
 
-One declared scene query/result for an exact pre-AA spatial/wavelength node.
+One declared scene query and its result, for one exact spatial and wavelength node before the
+anti-aliasing (AA) filter.
 
 ```ts
 export interface SceneSensorQuadratureSample {
@@ -66,9 +69,9 @@ export interface SceneToSensorIrradianceQuadrature {
   reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;
   samples: readonly {
     node: SensorSpatioSpectralNodeIdentity;
-    /** Physical source coordinate before AA redistribution, in mm. */
+    /** Physical source coordinate, in mm, before the anti-aliasing filter spreads it. */
     preAntiAliasingSourcePointMm: { x: number; y: number };
-    /** Owned provider target/time declaration; not a verified ray intersection. */
+    /** The provider's declared target and time. This is not a verified ray intersection. */
     request: SceneSensorQuadratureSample["sceneRadianceRequest"];
     result: SceneSensorQuadratureSample["sceneRadianceResult"];
     bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;

package/docs/api/optics-sensor-aperture-rays.md

@@ -1,10 +1,11 @@
 # optics/sensor-aperture-rays.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.
 
 ## calculateSensorApertureRays
 
-Uniform-area polar midpoint rule, normalized as an average, never a second f-number factor.
+Polar midpoint rule with equal-area cells. Weights are normalized as an average, so they never
+apply the f-number a second time.
 
 ```ts
 export function calculateSensorApertureRays(input: CalculateSensorApertureRaysInput): CalculationResult<SensorApertureRays>;

package/docs/api/optics-sensor-environment-query.md

@@ -1,13 +1,16 @@
 # optics/sensor-environment-query.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.
 
 ## calculateSensorEnvironmentRadianceQuery
 
-Generate an environment radiance request from physical sensor support using
-the existing focus-aware ideal projection and analytic inverse camera rotation.
-Native Y is explicitly inverted; the provider direction is opposite the
-exposure-start look ray. No scene intersection, radiance or renderer executes.
+Builds an environment radiance request from points on the physical sensor,
+using the existing focus-aware ideal projection and the analytic inverse
+camera rotation.
+
+Native Y (+Y down) is inverted explicitly. The provider direction points
+opposite the look ray at exposure start. Nothing intersects the scene,
+computes radiance or renders.
 
 ```ts
 export function calculateSensorEnvironmentRadianceQuery(
@@ -23,17 +26,54 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface CalculateSensorEnvironmentRadianceQueryInput {
-  /** Pre-AA or pre-PSF optical support, native +X right/+Y down, mm about optical axis. */
+  /** Optical sample point before the anti-aliasing filter or PSF. Native +X right, +Y down, in mm from the optical axis. */
   sourcePointNativeSensorMm: { x: number; y: number };
   focalLengthMm: number;
   focus: FocusPlane;
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
-  /** Explicitly maps the shutter opening boundary to the rotation model's t=0. */
+  /** States that the moment the shutter opens is t=0 in the rotation model. */
   timeReference: "first-opening-boundary-phase";
   timeSecondsFromOpeningReference: number;
-  /** Environment request uses radiance propagation toward the camera, opposite the look ray. */
+  /** The request uses the direction radiance travels: toward the camera, opposite the look ray. */
   environmentDirectionConvention: "outgoing-radiance-toward-camera";
   request: Omit<SceneRadianceEvaluationRequest, "target" | "timeSecondsFromExposureStart">;
+  /** Optional 2.0 lens field mapping. Omit it for the ideal rectilinear, distortion-free query. */
+  lensFieldMapping?: EnvironmentLensFieldMapping;
+}
+```
+
+## EnvironmentLensFieldMapping
+
+Lens field mapping between the physical (distorted) sensor point and the scene ray (2.0).
+`radiometricAreaCorrection` states who applies the distortion area factor. The environment
+photo signal multiplies irradiance by 1 / det(d distorted / d ideal) exactly once. A supplied
+field-throughput profile must therefore not include it as well.
+
+```ts
+export interface EnvironmentLensFieldMapping {
+  projectionModel: LensProjectionModel;
+  distortion:
+    | { kind: "none" }
+    | { kind: "radial"; profile: RadialDistortionProfile }
+    | { kind: "brown-conrady"; profile: BrownConradyDistortionProfile };
+  radiometricAreaCorrection: "inverse-distortion-jacobian";
+}
+```
+
+## SensorEnvironmentLensFieldMappingResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEnvironmentLensFieldMappingResult {
+  projectionModel: LensProjectionModel;
+  distortionKind: "none" | "radial" | "brown-conrady";
+  /** Ideal (undistorted) image-plane point, +X right / +Y up, mm. */
+  idealImagePointMm: { x: number; y: number };
+  /** Projection scale: thin-lens image distance at finite focus, focal length at infinity, mm. */
+  projectionScaleMm: number;
+  /** 1 / det(d distorted / d ideal) at this point; 1 without distortion. */
+  distortionAreaFactor: number;
 }
 ```
 
@@ -47,7 +87,10 @@ export interface SensorEnvironmentRadianceQuery {
   sourcePointNativeSensorMm: { x: number; y: number };
   sourcePointImagePlaneMm: { x: number; y: number };
   referenceLookDirectionUnitVector: { x: number; y: number; z: number };
-  projection: ReturnType<typeof calculateInverseCameraRotationImageMapping>;
+  /** Rectilinear rotation mapping. Null when a non-rectilinear lens field mapping is used. */
+  projection: ReturnType<typeof calculateInverseCameraRotationImageMapping> | null;
+  /** Present only when the input declared a lens field mapping. */
+  lensFieldMapping?: SensorEnvironmentLensFieldMappingResult;
   targetMeaning: "environment-direction-in-exposure-start-camera-axes";
   directionConvention: "outgoing-radiance-toward-camera";
   geometricRayProjectionCalculated: true;

package/docs/api/optics-sensor-psf-quadrature.md

@@ -1,13 +1,16 @@
 # optics/sensor-psf-quadrature.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.
 
 ## calculateSensorPsfIrradianceQuadrature
 
-Apply each resolved unit-energy PSF as a destination-local inverse sample sum.
-Native +Y-down support converts explicitly to optical +Y-up kernel orientation.
-No boundary extension, missing-support renormalization or extra throughput is
-applied. This approximation is not a field-dependent forward energy transport.
+Applies each resolved unit-energy PSF as an inverse sum of samples around
+each destination pixel.
+
+Support in native coordinates (+Y down) is converted explicitly to the
+optical kernel orientation (+Y up). The edges are not extended, missing
+support is not renormalized and no extra throughput is applied. This
+approximation is not a field-dependent forward transport of energy.
 
 ```ts
 export function calculateSensorPsfIrradianceQuadrature(
@@ -23,15 +26,15 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface CalculateSensorPsfIrradianceQuadratureInput {
-  /** One instant on the explicitly declared shutter opening reference. */
+  /** One instant, measured on the declared shutter-opening time reference. */
   timeSecondsFromOpeningReference: number;
   spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
   spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
-  /** The adapter owns wavelength and image-plane field position for each node. */
+  /** The adapter supplies the wavelength and image-plane field position for each node. */
   psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
-  /** Schema 0.1.0 PSF profiles lack a basis field; bind that source meaning explicitly. */
+  /** Schema 0.1.0 PSF profiles have no basis field, so the caller states what the source means. */
   psfWavelengthBasis: { value: "air" | "vacuum"; evidence: readonly EvidenceProvenance[] };
-  /** Explicit local approximation; a varying PSF grid is not a global convolution. */
+  /** Explicit local approximation. A PSF that varies across a grid is not a global convolution. */
   spatialModel: { kind: "destination-local-shift-invariant-approximation";
     evidence: readonly EvidenceProvenance[]; limitation: string };
   inputMeaning: "pre-psf-pre-sensor-stack-pre-aa-spectral-irradiance";
@@ -74,7 +77,7 @@ export interface SensorPsfSourceSample {
   timeSecondsFromOpeningReference: number;
   kernelSampleX: number;
   kernelSampleY: number;
-  /** Optical-axis origin, +X right/+Y down, millimetres; no native crop clipping. */
+  /** Origin on the optical axis, +X right, +Y down, in millimetres. Not clipped to the native crop. */
   sourcePointNativeSensorMm: { x: number; y: number };
   spectralIrradianceWattsPerSquareMeterPerNanometer: number;
 }

package/docs/api/optics-stray-light.md

@@ -1,12 +1,13 @@
 # optics/stray-light.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.
 
 ## calculateLensStrayLightIrradiance
 
-Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
-Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
-Gaussian templates are independently parameterized approximations, not lens prescription ray tracing.
+Adds off-path spectral irradiance before the sensor integrates the exposure, never after tone mapping.
+Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant and wavelength.
+The Gaussian templates are independently parameterized approximations, not ray tracing through a
+lens prescription.
 
 ```ts
 export function calculateLensStrayLightIrradiance(input: {
@@ -21,7 +22,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## LensStrayLightProfile
 
-Single explicit wavelength and exact generic camera state; clean optics only.
+One explicit wavelength and an exact generic camera state. Models clean optics only.
 
 ```ts
 export interface LensStrayLightProfile {
@@ -42,7 +43,7 @@ export interface LensStrayLightProfile {
 
 ## ParametricStrayLightResponse
 
-One reflected-path or broad scatter response, normalized over the infinite image plane.
+One ghost (reflection path) or veil (broad scatter) response. Its shape is normalized over the infinite image plane.
 
 ```ts
 export interface ParametricStrayLightResponse {
@@ -54,14 +55,14 @@ export interface ParametricStrayLightResponse {
   sigmaMm: number;
   /** Fraction of source power entering this response at the axis. */
   axisPowerFraction: number;
-  /** F(rho)=F(0)*(1+slope*rho²), rho=source angle/max angle. */
+  /** Power fraction versus angle: F(rho) = F(0) * (1 + slope * rho²), where rho = source angle / maximum angle. */
   angularSlope: number;
 }
 ```
 
 ## parseLensStrayLightProfile
 
-Strict generic profile parser; bounds passivity across the whole angular envelope.
+Strict generic profile parser. Checks that the profile adds no energy at any source angle in its range.
 
 ```ts
 export function parseLensStrayLightProfile(value: unknown): LensStrayLightProfile;
@@ -86,7 +87,7 @@ export interface StrayLightIrradiance {
   ghostSpectralIrradianceWPerM2PerNm: number;
   veilSpectralIrradianceWPerM2PerNm: number;
   totalSpectralIrradianceWPerM2PerNm: number;
-  /** If primary-only, the meter excludes these additions; sensor always receives total. */
+  /** If primary-only, the meter leaves these additions out. The sensor always receives the total. */
   meterDomain: "primary-only" | "primary-plus-stray";
   meterSpectralIrradianceWPerM2PerNm: number;
   contributions: readonly { sourceId: string; responseId: string; kind: "ghost" | "veil"; spectralIrradianceWPerM2PerNm: number }[];
@@ -95,7 +96,7 @@ export interface StrayLightIrradiance {
 
 ## StrayLightSource
 
-Direction remains available beyond the active frame; no crop clipping.
+The direction can lie outside the active frame. It is not clipped to the crop.
 
 ```ts
 export interface StrayLightSource {
@@ -103,7 +104,7 @@ export interface StrayLightSource {
   fieldAngleXDegrees: number;
   fieldAngleYDegrees: number;
   incidentSpectralPowerWPerNm: number;
-  /** Explicit source/path admission, e.g. a flag/hood decision; not a global hood scalar. */
+  /** Fraction of this source let in, for example after a flag or hood decision. Not a global hood factor. */
   admittedFraction: number;
 }
 ```