@photivra/engine 1.5.0 → 2.1.0

package/docs/api/optics-depth-of-field.md

@@ -1,11 +1,12 @@
 # optics/depth-of-field.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.
 
 ## calculateDefocusCircle
 
 Calculates the geometric defocus-circle diameter at the sensor plane for a
-subject plane away from the selected focus plane.
+subject plane away from the selected focus plane, using the stable closed
+form c = f^2 |s - d| / (N d (s - f)) (model 1.1.0).
 
 ```ts
 export function calculateDefocusCircle(
@@ -34,11 +35,16 @@ export interface CalculateDefocusCircleInput {
 
 ## calculateDepthOfField
 
-Calculates thin-lens depth-of-field limits using the conventional
-hyperfocal-distance formulation.
+Calculates exact thin-lens depth-of-field limits. With hyperfocal
+distance H = f^2/(Nc) + f and focus distance s, the near limit is
+s(H - f)/(H + s - 2f) and the far limit is s(H - f)/(H - s), which is
+infinite (`null`) when s >= H. At both limits the geometric defocus circle
+from {@link calculateDefocusCircle} equals the supplied circle of confusion.
+The circle of confusion must be smaller than the aperture diameter f/N;
+otherwise the near limit would fall inside the focal length.
 
-The model is geometric and does not include diffraction, aberrations,
-focus breathing, pupil magnification, or macro/high-magnification effects.
+The model is geometric. It does not include diffraction, aberrations,
+focus breathing, pupil magnification or macro (high-magnification) effects.
 
 ```ts
 export function calculateDepthOfField(

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

@@ -0,0 +1,96 @@
+# optics/diffraction-psf-profile.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.
+
+## createDiffractionLimitedPsfProfile
+
+Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+±`fieldHalfExtentMm` with the same kernel at every field node.
+
+```ts
+export function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateDiffractionLimitedPsfProfileInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateDiffractionLimitedPsfProfileInput {
+  /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */
+  aperture: "circular";
+  focalLengthMm: number;
+  apertureFNumber: number;
+  focus: FocusPlane;
+  /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */
+  wavelengthsNm: readonly number[];
+  /** Square sample pitch of every kernel, µm. */
+  samplePitchMicrometers: number;
+  /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */
+  kernelRadiusSamples: number;
+  /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */
+  fieldHalfExtentMm: { x: number; y: number };
+  profileId: string;
+}
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS
+
+Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit).
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS = Object.freeze({ maximumWavelengths: 64, maximumKernelRadiusSamples: 32 })
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_MODEL
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_MODEL = Object.freeze({
+  modelId: "photivra-diffraction-limited-circular-pupil-psf" as const, modelVersion: "1.0.0" as const })
+```
+
+## DiffractionLimitedPsfProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfProfile {
+  profile: LensSampledPsfProfile;
+  model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;
+  pupilDiameterMm: number;
+  pupilToImageDistanceMm: number;
+  workingFNumber: number;
+  kernelRadiusSamples: number;
+  samplePitchMicrometers: number;
+  wavelengths: readonly DiffractionLimitedPsfWavelength[];
+  /** Largest truncated energy over the wavelengths. */
+  maximumTruncatedEnergyFraction: number;
+  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre"; maximumRadialNodes: number; maximumAngularNodes: number };
+}
+```
+
+## DiffractionLimitedPsfWavelength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfWavelength {
+  wavelengthNm: number;
+  /** f_c = 1/(λ·N_w), cycles per µm. */
+  cutoffFrequencyCyclesPerMicrometer: number;
+  /** 1.21967·λ·N_w, µm. */
+  firstZeroRadiusMicrometers: number;
+  /** Σ of the cell energies inside the window before renormalization (of a total of 1). */
+  capturedEnergyFraction: number;
+  /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */
+  truncatedEnergyFraction: number;
+  /** Fraction of the renormalized kernel in the centre sample. */
+  centreSampleFraction: number;
+}
+```

package/docs/api/optics-diffraction.md

@@ -1,6 +1,6 @@
 # optics/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.
 
 ## AiryDisk
 
@@ -9,8 +9,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface AiryDisk {
   /**
-   * Diameter from the center of the diffraction pattern to the first dark-ring
-   * diameter, in micrometres: 2.44 * wavelength * f-number.
+   * Diameter of the first dark ring of the diffraction pattern, in
+   * micrometres: 2.44 * wavelength * f-number.
    */
   firstZeroDiameterMicrometers: number;
 }
@@ -18,11 +18,12 @@ export interface AiryDisk {
 
 ## calculateAiryDisk
 
-Calculates the first-zero Airy-disk diameter for an ideal circular aperture.
+Calculates the Airy-disk diameter to the first dark ring for an ideal
+circular aperture.
 
-This uses the established diffraction relation d = 2.44 * lambda * N.
-It is an independent implementation of the mathematical relation and does
-not model lens aberrations or non-circular pupil geometry.
+It uses the standard diffraction relation d = 2.44 * lambda * N. This is an
+independent implementation of that relation. It does not model lens
+aberrations or non-circular pupils.
 
 ```ts
 export function calculateAiryDisk(

package/docs/api/optics-focus-breathing.md

@@ -1,14 +1,15 @@
 # optics/focus-breathing.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.
 
 ## calculateFocusBreathingFieldOfView
 
-Calculates one-axis field of view for the generic declared-scale focus-
-breathing projection and reports the corresponding ideal thin-lens FOV.
+Calculates the one-axis field of view under the declared-scale
+focus-breathing model, and reports the ideal thin-lens field of view for
+comparison.
 
-A breathingProjectionScale of 1 reproduces the current focus-aware
-thin-lens field-of-view result exactly.
+A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field
+of view exactly.
 
 ```ts
 export function calculateFocusBreathingFieldOfView(
@@ -35,13 +36,13 @@ export interface CalculateFocusBreathingFieldOfViewInput
 Applies a caller-declared focus-breathing projection scale to the ideal
 Gaussian thin-lens projection for one focus state.
 
-Photivra does not infer the scale from focal length, focus distance, lens
-identity, or marketing data. A value of 1 exactly preserves the current
-thin-lens projection.
+Photivra does not guess the scale from focal length, focus distance, lens
+identity or marketing data. A scale of 1 keeps the thin-lens projection
+exactly.
 
-This is a generic approximation of focus-dependent projection/magnification,
-not a calibrated real-lens model. The physical focal length remains
-authoritative and unchanged.
+This is a generic approximation of how projection and magnification change
+with focus. It is not a calibrated real-lens model. The physical focal
+length is never changed and stays authoritative.
 
 ```ts
 export function calculateFocusBreathingProjection(
@@ -65,14 +66,61 @@ export interface CalculateFocusBreathingProjectionInput {
    * Caller-declared projection scale for this focus state, relative to the
    * ideal thin-lens image distance.
    *
-   * 1 means no additional breathing relative to the current thin-lens model.
-   * Values above 1 narrow framing / increase magnification; values below 1
-   * widen framing / reduce magnification.
+   * 1 means no breathing beyond the thin-lens model. Values above 1 narrow the
+   * framing (more magnification). Values below 1 widen it (less
+   * magnification).
    */
   breathingProjectionScale: number;
 }
 ```
 
+## calculateGeometricFocusBreathing
+
+Focus breathing derived from ideal focusing geometry, instead of a declared scale.
+
+- unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so
+  v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.
+- fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal
+  plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field
+  at the rear nodal point then stays the same, and the magnification is f_infinity / u.
+Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil
+magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also
+see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic
+Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and
+principal planes, so modelling their breathing needs a calibrated profile.
+
+```ts
+export function calculateGeometricFocusBreathing(
+  input: CalculateGeometricFocusBreathingInput
+): CalculationResult<GeometricFocusBreathing>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateGeometricFocusBreathingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateGeometricFocusBreathingInput {
+  /** Focal length at infinity focus, mm. */
+  focalLengthMm: number;
+  /**
+   * Photographic focus distance measured from the subject plane to the sensor (image) plane, in
+   * metres, as marked on lens distance scales.
+   */
+  subjectToSensorDistanceM: number;
+  /** Sensor/capture dimension along the axis of interest, mm. */
+  sensorDimensionMm: number;
+  focusingMethod: GeometricFocusingMethod;
+  /**
+   * Signed distance between the front and rear principal planes (the "hiatus"), in mm. Default 0
+   * (thin lens). The subject-to-sensor distance is u + hiatus + v.
+   */
+  principalPlaneSeparationMm?: number;
+}
+```
+
 ## FocusBreathingFieldOfView
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -105,8 +153,8 @@ export interface FocusBreathingProjection {
   /**
    * Effective projection distance used by the generic breathing model.
    *
-   * This is a projection/magnification parameter, not a replacement physical
-   * focal length.
+   * This is a projection (magnification) parameter. It does not replace the
+   * physical focal length.
    */
   effectiveProjectionDistanceMm: number;
   /** Caller-declared scale relative to ideal thin-lens projection. */
@@ -117,3 +165,43 @@ export interface FocusBreathingProjection {
   effectiveMagnification: number;
 }
 ```
+
+## GeometricFocusBreathing
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GeometricFocusBreathing {
+  focusingMethod: GeometricFocusingMethod;
+  infinityFocalLengthMm: number;
+  /** Focal length of the focused system (changes only for internal focus), mm. */
+  effectiveFocalLengthMm: number;
+  /** Subject distance from the front principal plane, mm. */
+  objectDistanceMm: number;
+  /** Rear principal plane to sensor distance (projection distance), mm. */
+  imageDistanceMm: number;
+  /** Lateral magnification v / u. */
+  magnification: number;
+  /** v / f_infinity: framing scale relative to infinity focus. */
+  projectionScaleRelativeToInfinity: number;
+  /**
+   * v divided by the ideal thin-lens image distance, at objectDistanceMm, of a lens with the same
+   * infinity focal length. Exactly 1 for unit focus. You can pass it as breathingProjectionScale to
+   * calculateFocusBreathingProjection() with focusDistanceM = objectDistanceMm / 1000.
+   */
+  equivalentBreathingProjectionScale: number;
+  fieldOfViewDegrees: number;
+  infinityFieldOfViewDegrees: number;
+  deltaDegrees: number;
+}
+```
+
+## GeometricFocusingMethod
+
+Ideal focusing geometry for {@link calculateGeometricFocusBreathing}.
+
+```ts
+export type GeometricFocusingMethod =
+  | "unit-focus"
+  | "fixed-image-distance-internal-focus";
+```

package/docs/api/optics-focus-state.md

@@ -1,14 +1,14 @@
 # optics/focus-state.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.
 
 ## calculateFocusPlaneImageDistance
 
 Calculates the ideal image-plane distance for an explicit focus state.
 
-Finite focus delegates to the existing Gaussian thin-lens calculation, so
-its numerical result and provenance are unchanged. Infinity focus resolves
-exactly to the nominal focal length with zero limiting magnification.
+Finite focus uses the existing Gaussian thin-lens calculation, so its
+numbers and provenance are unchanged. Infinity focus gives exactly the
+nominal focal length, with a limiting magnification of zero.
 
 ```ts
 export function calculateFocusPlaneImageDistance(
@@ -35,10 +35,9 @@ export interface CalculateFocusPlaneImageDistanceInput {
 
 Explicit ideal focus-plane state.
 
-Finite distance is the longitudinal object-plane distance from the ideal
-lens principal plane along the camera optical axis. Infinity is a semantic
-state and is never represented with JavaScript Infinity or a fabricated
-large distance.
+A finite distance is measured along the camera's optical axis, from the
+ideal lens principal plane to the object plane. Infinity is a named state.
+It is never stored as JavaScript Infinity or as a made-up large distance.
 
 ```ts
 export type FocusPlane =
@@ -53,9 +52,9 @@ export type FocusPlane =
 
 ## parseFocusPlane
 
-Parses an explicit focus-plane state from an untrusted JSON boundary.
+Parses an explicit focus-plane state from untrusted JSON.
 
-Missing/unknown focus is rejected rather than being interpreted as infinity.
+Missing or unknown focus is rejected. It is never read as infinity.
 
 ```ts
 export function parseFocusPlane(value: unknown): FocusPlane;

package/docs/api/optics-front-of-lens-filter.md

@@ -1,6 +1,6 @@
 # optics/front-of-lens-filter.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.
 
 ## ComposedFrontOfLensFilterTransmission
 
@@ -9,7 +9,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface ComposedFrontOfLensFilterTransmission {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   wavelengthNanometers: number;
   wavelengthBasis:
     Exclude<
@@ -28,8 +28,11 @@ export interface ComposedFrontOfLensFilterTransmission {
     "not-propagated";
   uncertaintyLimitation: string;
   compositionModel:
-    "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections";
-  polarizationModeled: false;
+    | "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections"
+    | "ordered-linear-stokes-mueller-no-inter-filter-reflections";
+  polarizationModeled: boolean;
+  incidentPolarization: LinearPolarizationState;
+  transmittedPolarization: LinearPolarizationState;
   wavelengthChangingBehaviorModeled:
     false;
   lensTransmissionIncluded: false;
@@ -40,8 +43,9 @@ export interface ComposedFrontOfLensFilterTransmission {
 
 ## composeFrontOfLensFilterTransmission
 
-Composes multiple passive front-of-lens filters multiplicatively at one
-wavelength while preserving each component's identity.
+Combines several passive front-of-lens filters at one wavelength, in light-path order, and keeps
+each filter's identity. Without a polarizer the result is the product of the transmissions. With
+one, linear Stokes parameters pass through the Mueller matrices in order.
 
 ```ts
 export function composeFrontOfLensFilterTransmission(
@@ -58,6 +62,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface ComposeFrontOfLensFilterTransmissionInput {
+  /** Filters in light-path order (scene side first). */
   filters:
     readonly FrontOfLensFilterProfile[];
   wavelengthNanometers: number;
@@ -66,6 +71,8 @@ export interface ComposeFrontOfLensFilterTransmissionInput {
       SpectralWavelengthBasis,
       "unspecified"
     >;
+  /** Incident scene polarization; omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
 }
 ```
 
@@ -78,6 +85,15 @@ FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION =
   "0.1.0" as const
 ```
 
+## FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION
+
+Schema that also allows the `linear-polarizer` transmission kind.
+
+```ts
+FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION =
+  "0.2.0" as const
+```
+
 ## FrontOfLensFilterProfile
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -85,7 +101,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface FrontOfLensFilterProfile {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   filterId: string;
   profileVersion: string;
   identityScope:
@@ -106,7 +122,8 @@ export interface FrontOfLensFilterProfile {
     FrontOfLensFilterTransmissionModel;
   uncertainty:
     FrontOfLensFilterUncertainty;
-  polarizationModeled: false;
+  /** True exactly when the transmission kind is `linear-polarizer` (schema 0.2.0). */
+  polarizationModeled: boolean;
   wavelengthChangingBehaviorModeled:
     false;
   evidence: readonly EvidenceProvenance[];
@@ -114,6 +131,16 @@ export interface FrontOfLensFilterProfile {
 }
 ```
 
+## FrontOfLensFilterProfileSchemaVersion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type FrontOfLensFilterProfileSchemaVersion =
+  | typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION
+  | typeof FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION;
+```
+
 ## FrontOfLensFilterScientificStatus
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -157,6 +184,18 @@ export type FrontOfLensFilterTransmissionModel =
         EvidenceBackedFact<
           readonly FrontOfLensFilterSpectralSample[]
         >;
+    }
+  | {
+      /** Schema 0.2.0 only. Neutral (wavelength-independent) within the declared range. */
+      kind: "linear-polarizer";
+      /** k1: intensity transmittance for light polarized along the transmission axis, (0, 1]. */
+      principalTransmittance:
+        EvidenceBackedFact<number>;
+      /** k1 / k2. Finite and >= 1. Use a large finite ratio for a near-ideal polarizer. */
+      extinctionRatio:
+        EvidenceBackedFact<number>;
+      /** Transmission-axis angle as mounted, degrees counter-clockwise from image +X. */
+      transmissionAxisDegrees: number;
     };
 ```
 
@@ -177,14 +216,27 @@ export type FrontOfLensFilterUncertainty =
     };
 ```
 
+## LinearPolarizationState
+
+Partially linearly polarized light: degree P in [0, 1] and polarization angle psi.
+
+```ts
+export interface LinearPolarizationState {
+  /** Degree of linear polarization P in [0, 1]; 0 is unpolarized. */
+  degreeOfLinearPolarization: number;
+  /** Electric-field polarization angle, degrees counter-clockwise from image +X. */
+  angleDegrees: number;
+}
+```
+
 ## parseFrontOfLensFilterProfile
 
 Parses one generic front-of-lens transmission filter.
 
 Schema 0.1.0 is explicitly unbranded and unpolarized. It models only
-passive transmission placed before the lens. Reflections between stacked
-filters, polarization, flare/ghosting and wavelength-changing behavior are
-outside this contract.
+passive transmission in front of the lens. It does not cover reflections
+between stacked filters, polarization, flare or ghosting, or filters that
+change wavelength.
 
 ```ts
 export function parseFrontOfLensFilterProfile(
@@ -201,7 +253,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface ResolvedFrontOfLensFilterTransmission {
   schemaVersion:
-    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    FrontOfLensFilterProfileSchemaVersion;
   filterId: string;
   profileVersion: string;
   identityScope:
@@ -217,10 +269,13 @@ export interface ResolvedFrontOfLensFilterTransmission {
     >;
   transmissionKind:
     FrontOfLensFilterTransmissionModel["kind"];
+  /** Intensity transmittance for the declared incident polarization. */
   linearTransmissionFactor: number;
   attenuationStops: number;
   opticalDensityBase10: number;
-  polarizationModeled: false;
+  polarizationModeled: boolean;
+  incidentPolarization: LinearPolarizationState;
+  transmittedPolarization: LinearPolarizationState;
   wavelengthChangingBehaviorModeled:
     false;
   lensTransmissionIncluded: false;
@@ -235,7 +290,8 @@ export interface ResolvedFrontOfLensFilterTransmission {
 
 ## resolveFrontOfLensFilterTransmission
 
-Resolves one passive filter at one wavelength.
+Resolves one passive filter at one wavelength. Non-polarizing filters scale all Stokes
+components equally, so their transmission does not depend on the incident polarization.
 
 ```ts
 export function resolveFrontOfLensFilterTransmission(
@@ -259,5 +315,7 @@ export interface ResolveFrontOfLensFilterTransmissionInput {
       SpectralWavelengthBasis,
       "unspecified"
     >;
+  /** Incident polarization; omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
 }
 ```

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

@@ -1,15 +1,15 @@
 # optics/illumination-vignetting.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.
 
 ## calculateIlluminationVignetting
 
-Calculates generic field-dependent illumination falloff as a multiplicative
-linear-light throughput factor.
+Calculates generic illumination falloff across the image (vignetting) as a
+factor that multiplies linear light.
 
-The profile is accepted only when its relative throughput remains strictly
-positive and never exceeds the optical-axis normalization of 1 throughout
-the complete declared operating envelope.
+A profile is accepted only if its relative throughput stays strictly
+positive and never exceeds 1 (the value on the optical axis) anywhere in
+its declared range.
 
 ```ts
 export function calculateIlluminationVignetting(
@@ -28,8 +28,8 @@ export interface CalculateIlluminationVignettingInput {
   /**
    * Ideal image-plane field position relative to the optical axis, in mm.
    *
-   * This slice evaluates throughput from the declared ideal field coordinate;
-   * it does not apply or invert geometric distortion.
+   * Throughput is evaluated at this ideal field coordinate. Geometric
+   * distortion is neither applied nor inverted.
    */
   imagePointMm: LensFieldPointMm;
   profile: IlluminationVignettingProfile;
@@ -45,9 +45,9 @@ export interface IlluminationVignetting {
   imagePointMm: LensFieldPointMm;
   normalizedRadius: number;
   /**
-   * Multiplicative factor for scene-linear/channel-linear signal.
+   * Factor that multiplies scene-linear or channel-linear signal.
    *
-   * 1 means no attenuation; values are required to remain in (0, 1].
+   * 1 means no attenuation. Values must stay in (0, 1].
    */
   linearThroughputFactor: number;
   /** Positive exposure loss relative to the optical axis, in stops. */