@photivra/engine 1.5.0 → 2.1.0

package/docs/api/optics-irradiance-convolution.md

@@ -0,0 +1,95 @@
+# optics/irradiance-convolution.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.
+
+## calculateIrradianceConvolution
+
+Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids.
+
+```ts
+export function calculateIrradianceConvolution(input: IrradianceConvolutionInput): { plan: IrradianceConvolutionPlan; values: Float64Array };
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateIrradianceConvolutionPlan
+
+Validates the request and returns its plan. Every sample and weight is checked once.
+
+```ts
+export function calculateIrradianceConvolutionPlan(input: IrradianceConvolutionInput): IrradianceConvolutionPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IRRADIANCE_CONVOLUTION_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({
+  maximumPixels: 24_000_000,
+  maximumDimension: 16_384,
+  maximumKernelRadius: 32,
+  maximumPatchCount: 4_096,
+  maximumKernelWeights: 4_194_304,
+  /** A kernel may lose energy (vignetting, transmission) but may not create it, beyond rounding slack. */
+  maximumKernelSum: 1 + 2 ** -20,
+  /** Inputs larger than this are rejected so that float32 execution cannot overflow. */
+  maximumSampleMagnitude: 2 ** 100
+})
+```
+
+## IRRADIANCE_CONVOLUTION_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+IRRADIANCE_CONVOLUTION_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## IrradianceConvolutionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IrradianceConvolutionInput {
+  schemaVersion: typeof IRRADIANCE_CONVOLUTION_SCHEMA_VERSION;
+  width: number;
+  height: number;
+  /** Row-major samples. Finite, non-negative, linear and additive (for example irradiance, or expected photons per site). */
+  samples: Float32Array | Float64Array;
+  /** Kernel half-width in grid sites. Each kernel is (2r+1)×(2r+1). */
+  kernelRadius: number;
+  /** Patch size in grid sites. The last row and column of patches may be partial. */
+  patchWidth: number;
+  patchHeight: number;
+  /**
+   * Finite non-negative weights, `[patchRow][patchColumn][v + r][u + r]`, one kernel per patch in
+   * row-major patch order. Each kernel sums to at most 1 (+2^-20 rounding slack).
+   */
+  kernels: Float32Array | Float64Array;
+  boundary: "zero-outside-grid";
+}
+```
+
+## IrradianceConvolutionPlan
+
+Validated, immutable geometry of a convolution request. Sample arrays are borrowed, not copied.
+
+```ts
+export interface IrradianceConvolutionPlan {
+  width: number;
+  height: number;
+  kernelRadius: number;
+  kernelSize: number;
+  tapCount: number;
+  patchWidth: number;
+  patchHeight: number;
+  patchColumns: number;
+  patchRows: number;
+  /** Largest kernel sum and largest input magnitude. The float32 error bound uses them. */
+  maximumKernelSum: number;
+  maximumSampleMagnitude: number;
+}
+```

package/docs/api/optics-lateral-chromatic-aberration.md

@@ -1,14 +1,14 @@
 # optics/lateral-chromatic-aberration.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.
 
 ## calculateInverseLateralChromaticAberrationMapping
 
-Inverse-maps one distorted output destination independently for the
-representative red/green/blue channels.
+Inverse-maps one distorted output point separately for the representative
+red, green and blue channels.
 
-Renderers can use the returned per-channel ideal source coordinates for
-inverse sampling without inventing chromatic-aberration equations.
+Renderers can sample the returned per-channel ideal source points directly,
+without writing their own chromatic-aberration equations.
 
 ```ts
 export function calculateInverseLateralChromaticAberrationMapping(
@@ -25,8 +25,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CalculateInverseLateralChromaticAberrationMappingInput {
   /**
-   * Distorted output image-plane destination. Each output channel is inverse-
-   * mapped independently to its ideal source coordinate.
+   * Distorted output image-plane point. Each channel is inverse-mapped on its
+   * own to its ideal source point.
    */
   distortedImagePointMm: LensFieldPointMm;
   profile: LateralChromaticAberrationProfile;
@@ -35,12 +35,12 @@ export interface CalculateInverseLateralChromaticAberrationMappingInput {
 
 ## calculateInverseLateralChromaticAberrationMappings
 
-Inverse-maps multiple distorted destinations while resolving the shared CA
-profile once and validating each combined channel profile once for the
-complete batch.
+Inverse-maps many distorted points at once. The shared CA profile is
+resolved once, and each combined channel profile is validated once, for
+the whole batch.
 
-Per-point values match calculateInverseLateralChromaticAberrationMapping();
-provenance is shared once at the batch boundary.
+Each point's values match calculateInverseLateralChromaticAberrationMapping().
+Provenance is reported once for the batch.
 
 ```ts
 export function calculateInverseLateralChromaticAberrationMappings(
@@ -57,9 +57,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface CalculateInverseLateralChromaticAberrationMappingsInput {
   /**
-   * Distorted output image-plane destinations. Each destination is inverse-
-   * mapped independently for red, green, and blue after one profile-resolution
-   * step for the batch.
+   * Distorted output image-plane points. The profile is resolved once for the
+   * batch. Then each point is inverse-mapped separately for red, green and
+   * blue.
    */
   distortedImagePointsMm: readonly LensFieldPointMm[];
   profile: LateralChromaticAberrationProfile;
@@ -68,11 +68,12 @@ export interface CalculateInverseLateralChromaticAberrationMappingsInput {
 
 ## calculateLateralChromaticAberrationMapping
 
-Calculates generic lateral chromatic-aberration field separation by mapping
-one ideal image-plane point through a shared green-reference base distortion
-and red/blue radial coefficient offsets.
+Calculates how far lateral chromatic aberration (CA) separates the colour
+channels at one ideal image-plane point. The point goes through a shared
+base distortion (green is the reference) plus extra radial coefficients for
+red and blue.
 
-This is channel-dependent field mapping, not a blur kernel.
+This moves each channel; it is not a blur kernel.
 
 ```ts
 export function calculateLateralChromaticAberrationMapping(
@@ -200,8 +201,8 @@ export interface LateralChromaticAberrationProfile {
   /**
    * Green-reference base geometric distortion.
    *
-   * This common mapping is included in every channel. Red/blue CA terms are
-   * added to this base, so callers should not apply a second distortion pass.
+   * Every channel includes this shared mapping. The red and blue CA terms are
+   * added on top of it, so do not apply a second distortion pass.
    */
   baseDistortionCoefficients: RadialDistortionCoefficients;
   /** Additional red-channel radial coefficients relative to green. */

package/docs/api/optics-lens-psf-kernels.md

@@ -0,0 +1,72 @@
+# optics/lens-psf-kernels.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.
+
+## LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS
+
+At most this many wavelengths per call.
+
+```ts
+LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64
+```
+
+## LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## LensPsfConvolutionKernels
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfConvolutionKernels {
+  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+  kernelRadius: number;
+  patchWidth: number;
+  patchHeight: number;
+  patchColumns: number;
+  patchRows: number;
+  /** `[patchRow][patchColumn][v + r][u + r]`, ready for `IrradianceConvolutionInput.kernels`. */
+  kernels: Float64Array;
+  /** True when every tap landed on one integer displacement (no bilinear splatting). */
+  exactSiteSampling: boolean;
+  maximumKernelSum: number;
+  /** Per patch, row-major: the field point used and the weight-averaged relative pupil throughput (not applied). */
+  patches: readonly { fieldPointMm: { x: number; y: number }; relativePupilThroughputFactor: number; interpolated: boolean }[];
+}
+```
+
+## LensPsfConvolutionKernelsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfConvolutionKernelsInput {
+  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+  /** The optical state, as for `resolveLensSampledPsf`, without the field point and wavelength. */
+  psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
+  /** One or more wavelengths with non-negative weights (at least one positive). */
+  spectralWeights: readonly { wavelengthNm: number; weight: number }[];
+  /** The convolution grid: sites, their pitch, and the optical axis in site units (site centres at i + 0.5). */
+  grid: { width: number; height: number; sitePitchMicrometers: { x: number; y: number }; opticalAxisSite: { x: number; y: number } };
+  /** Patch size in sites; the last row and column of patches may be partial. */
+  patchWidth: number;
+  patchHeight: number;
+  /** Kernel radius to use; omitted, the smallest radius that holds every tap. A radius too small to hold the PSF is rejected. */
+  kernelRadius?: number;
+}
+```
+
+## resolveLensPsfConvolutionKernels
+
+Builds the per-patch convolution kernels from a sampled lens PSF profile.
+
+```ts
+export function resolveLensPsfConvolutionKernels(input: LensPsfConvolutionKernelsInput): CalculationResult<LensPsfConvolutionKernels>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/optics-lens-psf-profile.md

@@ -1,16 +1,16 @@
 # optics/lens-psf-profile.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.
 
 ## assessMtfOnlyPsfRenderability
 
-Explain why MTF-only evidence cannot determine a unique renderable PSF; return blockers instead of
-fabricating phase information.
+Explains why MTF-only evidence cannot determine one unique renderable PSF. Returns blockers instead
+of making up phase information.
 
-Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
-support. Interpolation stays within declared applicability and preserves normalized shape separately
-from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
-unique PSF.
+A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+has no phase or spatial information, so it cannot justify rendering one unique PSF.
 
 ```ts
 export function assessMtfOnlyPsfRenderability(
@@ -189,6 +189,28 @@ export interface LensSampledPsfGridNode {
 }
 ```
 
+## LensSampledPsfInterpolation
+
+Kernel interpolation between regular-grid nodes.
+- `bounded-regular-grid-multilinear`: the legacy weighted sum of kernel values. Blending kernels
+  whose peaks sit at different positions gives several peaks.
+- `bounded-regular-grid-centroid-aligned`: each node kernel is first shifted so its intensity
+  centroid sits at the weighted (interpolated) centroid. Then the same multilinear weights are
+  applied. Shifted or asymmetric PSFs therefore blend into one peak at the interpolated position.
+- `rotationally-symmetric-radial-field-centroid-aligned`: for a rotationally symmetric lens. Nodes
+  are declared only along the +X field axis (fieldYmm = [0], fieldXmm >= 0). A query at field
+  (x, y) is interpolated, with centroid alignment, at radius hypot(x, y). The kernel is then
+  rotated by atan2(y, x) about its centre. The sample pitch must be square.
+Shifts and rotations use bilinear resampling. This smooths the kernel slightly (by at most about
+one sample). Samples outside the kernel are zero, and the result is renormalised to unit energy.
+
+```ts
+export type LensSampledPsfInterpolation =
+  | "bounded-regular-grid-multilinear"
+  | "bounded-regular-grid-centroid-aligned"
+  | "rotationally-symmetric-radial-field-centroid-aligned";
+```
+
 ## LensSampledPsfProfile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -210,7 +232,7 @@ export interface LensSampledPsfProfile {
   kernelEnergyNormalization:
     "unit-energy-shape";
   interpolation:
-    "bounded-regular-grid-multilinear";
+    LensSampledPsfInterpolation;
   throughputOwnership:
     "separate-relative-pupil-throughput-factor";
   responseIncludes: {
@@ -253,13 +275,13 @@ export interface MtfOnlyPsfRenderabilityAssessment {
 
 ## parseLensMtfDiagnosticProfile
 
-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 declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
-support. Interpolation stays within declared applicability and preserves normalized shape separately
-from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
-unique PSF.
+A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+has no phase or spatial information, so it cannot justify rendering one unique PSF.
 
 ```ts
 export function parseLensMtfDiagnosticProfile(
@@ -271,13 +293,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseLensSampledPsfProfile
 
-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 declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
-support. Interpolation stays within declared applicability and preserves normalized shape separately
-from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
-unique PSF.
+A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+has no phase or spatial information, so it cannot justify rendering one unique PSF.
 
 ```ts
 export function parseLensSampledPsfProfile(
@@ -341,13 +363,13 @@ export interface ResolvedLensSampledPsf {
 
 ## resolveLensSampledPsf
 
-Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
-or silently inventing missing dimensions.
+Resolves the sampled PSF for a declared optical state and query point. It never extrapolates and
+never invents missing dimensions.
 
-Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
-support. Interpolation stays within declared applicability and preserves normalized shape separately
-from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
-unique PSF.
+A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+has no phase or spatial information, so it cannot justify rendering one unique PSF.
 
 ```ts
 export function resolveLensSampledPsf(

package/docs/api/optics-longitudinal-chromatic-aberration.md

@@ -0,0 +1,128 @@
+# optics/longitudinal-chromatic-aberration.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.
+
+## calculateCauchyRefractiveIndex
+
+Two-term Cauchy refractive index fitted to n_d and V_d. Valid as an approximation over
+360-830 nm only.
+
+```ts
+export function calculateCauchyRefractiveIndex(input: {
+  refractiveIndexD: number;
+  abbeNumberD: number;
+  wavelengthNm: number;
+}): CalculationResult<{ refractiveIndex: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateLongitudinalChromaticFocus
+
+Wavelength-dependent focus for one wavelength: focal length, image distance, signed defocus at
+a sensor focused at the reference wavelength, geometric blur and the defocus wavefront.
+
+```ts
+export function calculateLongitudinalChromaticFocus(
+  input: CalculateLongitudinalChromaticFocusInput
+): CalculationResult<LongitudinalChromaticFocus>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLongitudinalChromaticFocusInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLongitudinalChromaticFocusInput {
+  /** Focal length at the reference wavelength, in mm. */
+  focalLengthMm: number;
+  /** Wavelength at which the sensor is focused, in nm. */
+  referenceWavelengthNm: number;
+  /** Wavelength to evaluate, in nm (same wavelength basis as the dispersion data). */
+  wavelengthNm: number;
+  /** Nominal f-number at the reference wavelength (entrance-pupil diameter = f / N). */
+  apertureFNumber: number;
+  /** Focus (object) distance at the reference wavelength, metres from the principal plane. */
+  focusDistanceM: number;
+  /** Subject distance in metres; defaults to focusDistanceM. */
+  subjectDistanceM?: number;
+  dispersion: LongitudinalChromaticDispersion;
+}
+```
+
+## FRAUNHOFER_C_LINE_NM
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FRAUNHOFER_C_LINE_NM = 656.2725
+```
+
+## FRAUNHOFER_D_LINE_NM
+
+Fraunhofer spectral-line wavelengths in nm (SCHOTT TIE-29 table; also ISO 7944 reference wavelengths).
+
+```ts
+FRAUNHOFER_D_LINE_NM = 587.5618
+```
+
+## FRAUNHOFER_F_LINE_NM
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FRAUNHOFER_F_LINE_NM = 486.1327
+```
+
+## LongitudinalChromaticDispersion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LongitudinalChromaticDispersion =
+  | {
+      kind: "thin-singlet-abbe";
+      /** Refractive index at the d line. */
+      refractiveIndexD: number;
+      /** Abbe number V_d = (n_d - 1) / (n_F - n_C). */
+      abbeNumberD: number;
+    }
+  | {
+      kind: "declared-focal-shift";
+      /** Strictly increasing wavelengths; shift is f(lambda) - f_nominal in micrometres. */
+      samples: readonly {
+        wavelengthNm: number;
+        focalLengthShiftMicrometers: number;
+      }[];
+    };
+```
+
+## LongitudinalChromaticFocus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LongitudinalChromaticFocus {
+  wavelengthNm: number;
+  referenceWavelengthNm: number;
+  focalLengthAtWavelengthMm: number;
+  /** f(lambda) - f(reference), micrometres. */
+  focalShiftMicrometers: number;
+  /** Sensor plane distance (reference-wavelength image of the focus plane), mm. */
+  sensorImageDistanceMm: number;
+  /** Image distance of the subject at this wavelength, mm. */
+  imageDistanceAtWavelengthMm: number;
+  /** Sensor minus image distance, micrometres. */
+  signedDefocusImagePlaneMicrometers: number;
+  /** Geometric thin-lens blur-circle diameter at the sensor, mm. */
+  geometricBlurDiameterMm: number;
+  /** Image-side working f-number v(lambda) / D. */
+  workingFNumberAtWavelength: number;
+  /** Defocus wave aberration W020 for the complex-pupil PSF, micrometres. */
+  w020Micrometers: number;
+  /** Equivalent Noll Z4 coefficient, micrometres. */
+  zernikeZ4Micrometers: number;
+}
+```

package/docs/api/optics-polygon-diffraction.md

@@ -1,6 +1,6 @@
 # optics/polygon-diffraction.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.
 
 ## CalculateIdealPolygonDiffractionInput
 
@@ -10,9 +10,9 @@ On-axis, in-focus scalar diffraction of one ideal regular polygon pupil.
 export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApertureInput {
   /** Diameter of a circle with the SAME AREA as the physical polygon opening. */
   equivalentAreaPupilDiameterMm: number;
-  /** Paraxial pupil-to-image propagation scale; not silently inferred from focus. */
+  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
   pupilToImageDistanceMm: number;
-  /** Wavelength in the declared propagation medium; no air/vacuum conversion. */
+  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
   wavelengthNm: number;
   wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
   /** Displacements from the on-axis PSF center, +X right / +Y up; at most 4096. */
@@ -22,15 +22,19 @@ export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApe
 
 ## calculateIdealPolygonDiffractionPsf
 
-Calculates continuous monochromatic Fraunhofer PSF density for a uniformly
-illuminated, zero-phase, on-axis ideal straight-edged regular polygon.
-Physical area is explicit; f/N may supply the equal-area diameter only under
-a declared nominal-area convention. No phase aberration, clipping, field
-dependence, curved blades, defocus or polychromatic behavior is inferred.
+Calculates the continuous, single-wavelength Fraunhofer (far-field) PSF
+density of an ideal regular polygon with straight edges. The pupil is
+uniformly lit, has zero phase and sits on the optical axis.
 
-Density = A |F/A|² / (lambda * propagationDistance)². Parseval normalization
-is over the infinite plane, NOT over the supplied point list. Downstream
-quadrature must preserve density × area and report truncation/convergence.
+The physical area is explicit. f/N may supply the equal-area diameter only
+when the caller declares the nominal-area convention. Nothing else is
+assumed: no phase aberration, clipping, field dependence, curved blades,
+defocus or multi-wavelength behaviour.
+
+Density = A |F/A|² / (lambda * propagationDistance)². It integrates to 1
+over the infinite plane (Parseval), NOT over the supplied points. Code that
+sums the samples must keep density × area and report truncation and
+convergence.
 
 ```ts
 export function calculateIdealPolygonDiffractionPsf(
@@ -40,9 +44,47 @@ export function calculateIdealPolygonDiffractionPsf(
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## calculatePolygonPupilFraunhoferPsf
+
+Continuous, single-wavelength Fraunhofer PSF density for any simple polygon pupil that is uniformly
+lit and has zero phase (for example a cat's-eye pupil from mechanical vignetting).
+
+It uses the same analytic edge integral as the regular-polygon model, so there is no aliasing from
+a pupil grid. Moving the pupil off the axis only adds a linear phase; the intensity does not
+change. Density = A |F/A|² / (lambda z)², and it integrates to 1 over the infinite plane.
+
+```ts
+export function calculatePolygonPupilFraunhoferPsf(
+  input: CalculatePolygonPupilFraunhoferPsfInput
+): CalculationResult<PolygonPupilFraunhoferPsf>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePolygonPupilFraunhoferPsfInput
+
+On-axis scalar Fraunhofer diffraction of one arbitrary simple polygon pupil.
+
+```ts
+export interface CalculatePolygonPupilFraunhoferPsfInput {
+  /**
+   * Simple (non-self-intersecting) pupil polygon in pupil-plane millimetres, +X right / +Y up,
+   * with 3 to 4096 vertices. For example, the cat's-eye pupil from calculateMechanicalVignetting().
+   */
+  pupilVerticesMm: readonly { x: number; y: number }[];
+  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
+  pupilToImageDistanceMm: number;
+  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  /** Displacements from the PSF centre (the geometric image point), +X right / +Y up; at most 4096. */
+  imagePointsMicrometers: readonly { x: number; y: number }[];
+}
+```
+
 ## IdealPolygonDiffraction
 
-Continuous unit-energy PSF samples, not a normalized finite convolution kernel.
+Samples of a continuous unit-energy PSF. This is not a normalized finite convolution kernel.
 
 ```ts
 export interface IdealPolygonDiffraction {
@@ -59,7 +101,30 @@ export interface IdealPolygonDiffraction {
   throughputApplied: false;
   samples: readonly {
     imagePointMicrometers: { x: number; y: number };
-    /** |F/A|²; unity at the origin. Not an energy/probability weight. */
+    /** |F/A|². Equal to 1 at the origin. Not an energy or probability weight. */
+    peakNormalizedIntensity: number;
+    /** Density integrating to unity over the full image plane, in 1/µm². */
+    intensityDensityPerSquareMicrometer: number;
+  }[];
+}
+```
+
+## PolygonPupilFraunhoferPsf
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PolygonPupilFraunhoferPsf {
+  pupilAreaSquareMm: number;
+  pupilToImageDistanceMm: number;
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  fieldAxes: "+X right, +Y up";
+  energyNormalization: "unit-integral-over-infinite-image-plane";
+  throughputApplied: false;
+  samples: readonly {
+    imagePointMicrometers: { x: number; y: number };
+    /** |F/A|²; unity at the origin. */
     peakNormalizedIntensity: number;
     /** Density integrating to unity over the full image plane, in 1/µm². */
     intensityDensityPerSquareMicrometer: number;