@photivra/engine 1.5.0 → 2.0.0

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;
 }
 ```

package/docs/api/optics-thin-lens.md

@@ -1,6 +1,6 @@
 # optics/thin-lens.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.
 
 ## calculateThinLensImageDistance
 
@@ -10,8 +10,9 @@ Calculates Gaussian thin-lens image distance:
 
 where f is focal length, s is object distance, and v is image distance.
 
-This is a paraxial ideal-lens model. It does not model real-lens focus
-breathing, pupil magnification, principal-plane movement, or aberrations.
+This is a paraxial (small-angle) ideal-lens model. It does not model
+real-lens focus breathing, pupil magnification, principal-plane movement
+or aberrations.
 
 ```ts
 export function calculateThinLensImageDistance(

package/docs/api/optics-zernike-wavefront.md

@@ -0,0 +1,229 @@
+# optics/zernike-wavefront.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.
+
+## calculateDefocusWavefront
+
+Converts a signed paraxial image-plane defocus into the defocus wave aberration
+W020 = dz / (8 N^2) and its Noll Z4 coefficient W020 / (2 sqrt 3).
+
+Sign convention: dz = sensor distance minus image distance. Positive W020 means the image lies in
+front of the sensor. With pure defocus, the PSF intensity does not depend on the sign.
+
+```ts
+export function calculateDefocusWavefront(
+  input: CalculateDefocusWavefrontInput
+): CalculationResult<DefocusWavefront>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDefocusWavefrontInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDefocusWavefrontInput {
+  /** Signed image-plane defocus, sensor minus image distance, in micrometres. */
+  signedDefocusImagePlaneMicrometers: number;
+  /** Image-side working f-number (image distance / pupil diameter). */
+  workingFNumber: number;
+}
+```
+
+## createWavefrontPupilGrid
+
+Builds a complex-pupil grid: a circular pupil, an optional polygon mask, and an OPD from Zernike
+coefficients, Seidel coefficients or both. If every coefficient is zero, the OPD is exactly zero,
+so the PSF equals the existing aberration-free circular-pupil reference.
+
+```ts
+export function createWavefrontPupilGrid(
+  input: CreateWavefrontPupilGridInput
+): CalculationResult<WavefrontPupilGrid>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateWavefrontPupilGridInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateWavefrontPupilGridInput {
+  /** Pupil diameter in mm; rho = 1 at radius pupilDiameterMm / 2. */
+  pupilDiameterMm: number;
+  /** Odd number of samples across the pupil diameter, from 3 to 63. */
+  samplesAcross: number;
+  zernikeCoefficients?: readonly ZernikeCoefficient[];
+  seidelCoefficients?: SeidelWavefrontCoefficients;
+  /** Required when any field-dependent Seidel coefficient is non-zero. */
+  seidelField?: SeidelFieldPosition;
+  /**
+   * Optional additional aperture mask: a simple polygon in pupil-plane mm (for example the
+   * cat's-eye pupil from calculateMechanicalVignetting). Samples outside it get zero amplitude.
+   */
+  apertureMaskVerticesMm?: readonly { x: number; y: number }[];
+}
+```
+
+## DefocusWavefront
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DefocusWavefront {
+  signedDefocusImagePlaneMicrometers: number;
+  workingFNumber: number;
+  /** Peak defocus coefficient W020 = dz / (8 N^2), micrometres. */
+  w020Micrometers: number;
+  /** Equivalent Noll Z4 coefficient W020 / (2 sqrt 3), micrometres (equals the RMS). */
+  zernikeZ4Micrometers: number;
+}
+```
+
+## estimateMarechalStrehlRatio
+
+Marechal/Mahajan approximation of the Strehl ratio: exp(-(2 pi sigma / lambda)^2). Valid only for a
+small RMS wavefront error (Strehl roughly above 0.3). It is not an exact PSF calculation.
+
+```ts
+export function estimateMarechalStrehlRatio(
+  input: EstimateMarechalStrehlRatioInput
+): CalculationResult<{ strehlRatio: number; rmsWaves: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateMarechalStrehlRatioInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateMarechalStrehlRatioInput {
+  rmsWavefrontErrorMicrometers: number;
+  wavelengthNm: number;
+}
+```
+
+## evaluateZernikePolynomial
+
+Evaluates the unit-RMS Noll Zernike polynomial at normalised pupil polar coordinates.
+
+```ts
+export function evaluateZernikePolynomial(
+  nollIndex: number,
+  normalizedRadius: number,
+  azimuthRadians: number
+): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveZernikeNollOrder
+
+Converts a Noll index to radial order n and signed azimuthal frequency m (Noll 1976).
+
+```ts
+export function resolveZernikeNollOrder(nollIndex: number): ZernikeOrder;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SeidelFieldPosition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SeidelFieldPosition {
+  /** Normalised field height H in [0, 1]. */
+  normalizedFieldHeight: number;
+  /** Image-plane direction of the field point, degrees counter-clockwise from +X. */
+  fieldAzimuthDegrees: number;
+}
+```
+
+## SeidelWavefrontCoefficients
+
+Peak Seidel wave-aberration coefficients in micrometres of optical path difference.
+
+```ts
+export interface SeidelWavefrontCoefficients {
+  /** Defocus rho^2. */
+  w020Micrometers?: number;
+  /** Tilt H rho cos(phi). */
+  w111Micrometers?: number;
+  /** Spherical aberration rho^4. */
+  w040Micrometers?: number;
+  /** Coma H rho^3 cos(phi). */
+  w131Micrometers?: number;
+  /** Astigmatism H^2 rho^2 cos^2(phi). */
+  w222Micrometers?: number;
+  /** Field curvature H^2 rho^2. */
+  w220Micrometers?: number;
+  /** Distortion H^3 rho cos(phi). */
+  w311Micrometers?: number;
+}
+```
+
+## WavefrontPupilGrid
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WavefrontPupilGrid {
+  /** Grid for LensComplexPupilProfile.grid. Amplitude is 1 inside and 0 outside; OPD is in micrometres. */
+  grid: LensComplexPupilGrid;
+  pupilDiameterMm: number;
+  /** Number of samples with non-zero amplitude. */
+  openSampleCount: number;
+  /** sqrt(sum c_j^2, j >= 2): RMS of the Zernike terms alone over the continuous unit disk. */
+  zernikeRmsMicrometers: number;
+  /** RMS of the sampled OPD over open samples, with piston removed (all terms). */
+  sampledRmsMicrometers: number;
+  /** Peak-to-valley of the sampled OPD over open samples. */
+  sampledPeakToValleyMicrometers: number;
+}
+```
+
+## ZERNIKE_MAXIMUM_NOLL_INDEX
+
+Largest supported Noll index (radial order n <= 10).
+
+```ts
+ZERNIKE_MAXIMUM_NOLL_INDEX = 66
+```
+
+## ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS
+
+Largest odd pupil grid width: 63 x 63 = 3969 samples, within the complex-pupil 4096 limit.
+
+```ts
+ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS = 63
+```
+
+## ZernikeCoefficient
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ZernikeCoefficient {
+  nollIndex: number;
+  /** Coefficient of the unit-RMS Noll polynomial, in micrometres of optical path difference. */
+  coefficientMicrometers: number;
+}
+```
+
+## ZernikeOrder
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ZernikeOrder {
+  nollIndex: number;
+  /** Radial order n. */
+  radialOrder: number;
+  /** Signed azimuthal frequency m. Positive means cos(m theta); negative means sin(|m| theta). */
+  azimuthalFrequency: number;
+}
+```

package/docs/api/output-capture-corrected-sdr.md

@@ -1,10 +1,11 @@
 # output/capture-corrected-sdr.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.
 
 ## calculateCaptureCorrectedSdr
 
-Bounded committed capture → color/WB → native correction → oriented output view → SDR. No physical stage activation.
+Runs a bounded committed capture through colour/WB → native lens correction → oriented output
+view → SDR. No physical simulation stage is run.
 
 ```ts
 export function calculateCaptureCorrectedSdr(input: CaptureCorrectedSdrInput): CalculationResult<CaptureCorrectedSdrResult>;
@@ -22,14 +23,15 @@ CAPTURE_CORRECTED_SDR_SCHEMA_VERSION = "0.1.0" as const
 
 ## CaptureCorrectedSdrInput
 
-Explicit native-optical correction binding. Body/lens/mode identities remain producer declarations.
+Input: a capture plus an explicit lens-correction choice in native optical coordinates. Camera
+body, lens and mode identities are taken as the capture producer declared them.
 
 ```ts
 export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
   correction: {
     profile: GenericLensCorrectionProfile;
     state: OpticalProfileState;
-    /** Native optical +X right/+Y up, RGB basis after the selected color/WB operation. */
+    /** Native optical coordinates (+X right, +Y up), in the RGB space after the selected colour/WB step. */
     coordinateFrame: "native-optical-linear-srgb-d65";
     selections: Readonly<Record<string, "on" | "off" | "auto">>;
     selectionKind: ResolvedLensCorrectionPlan["selectionKind"];
@@ -45,7 +47,7 @@ export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
 
 ## CaptureCorrectedSdrResult
 
-Derived output view, never a replacement for the committed capture's physical geometry.
+A derived output view. It never replaces the committed capture's physical geometry.
 
 ```ts
 export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schemaVersion"> {
@@ -54,7 +56,7 @@ export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schem
   plan: CalculationResult<ResolvedLensCorrectionPlan>;
   correction: ReturnType<typeof calculateLensCorrectedCapture>;
   projection: ReturnType<typeof calculateFieldOfView>;
-  /** Oriented full-output support; child correction plans retain native optical coordinates. */
+  /** Valid-source mask over the full oriented output. The nested correction plans still use native optical coordinates. */
   validSourceMask: readonly boolean[];
   outputView: { imageStateId: string; rect: RasterRect; pixelWidth: number; pixelHeight: number; samples: readonly number[] };
 }
@@ -62,7 +64,8 @@ export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schem
 
 ## parseCaptureCorrectedSdrInput
 
-Strict boundary; execution also checks capture optics, native raster binding and source history.
+Strictly parses untrusted input. Running the calculation also checks the capture's optics,
+native pixel-grid binding and source history.
 
 ```ts
 export function parseCaptureCorrectedSdrInput(input: unknown): CaptureCorrectedSdrInput;