@photivra/engine 1.5.0 → 2.1.0

package/docs/api/sensor-responsivity-photocurrent.md

@@ -1,15 +1,14 @@
 # sensor/responsivity-photocurrent.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.
 
 ## calculateSensorResponsivityPhotocurrent
 
-Integrate per-wavelength A/W times radiant-power contributions to steady-state current magnitude
-with explicit electrical applicability.
+Sums responsivity (A/W) × radiant power over wavelength bins to get the steady current magnitude,
+under explicit electrical conditions.
 
-A/W response converts per-bin radiant power to quasi-static detector-terminal current magnitude.
-Electrical bias/load applicability is explicit. This is not EQE, electron rate, transimpedance
-voltage or RAW; rapidly varying current requires a separate temporal detector-response model.
+This is not EQE, an electron rate, a transimpedance voltage or RAW. Fast-changing current needs a
+separate time-dependent detector model.
 
 ```ts
 export function calculateSensorResponsivityPhotocurrent(
@@ -45,12 +44,10 @@ export interface CalculateSensorResponsivityPhotocurrentInput {
 
 ## parseSensorResponsivityElectricalApplicabilityProfile
 
-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 untrusted input and returns it as a normalized, typed value. Unknown enum values,
+missing required fields and inconsistent scientific data are rejected.
 
-A/W response converts per-bin radiant power to quasi-static detector-terminal current magnitude.
-Electrical bias/load applicability is explicit. This is not EQE, electron rate, transimpedance
-voltage or RAW; rapidly varying current requires a separate temporal detector-response model.
+The profile states the electrical bias and load conditions under which an A/W responsivity applies.
 
 ```ts
 export function parseSensorResponsivityElectricalApplicabilityProfile(
@@ -141,7 +138,7 @@ export interface SensorResponsivityPhotocurrent {
   operatingRangeProfileId: string;
   electricalApplicabilityProfileId:
     string;
-  /** Engine-produced results populate the exact source color site. */
+  /** The exact source colour site. Results produced by the engine fill this in. */
   site?: {
     x: number;
     y: number;

package/docs/api/sensor-sampling-aperture.md

@@ -1,6 +1,6 @@
 # sensor/sampling-aperture.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.
 
 ## NativeSensorPhysicalBoundsMm
 
@@ -28,14 +28,13 @@ export interface NativeSensorPhysicalPointMm {
 
 ## parseSensorSamplingApertureProfile
 
-Parses physical registration of the color-site lattice plus a first geometric
-photosensitive-aperture model.
+Parses where the colour-sampling sites sit physically, plus a simple geometric
+model of each site's light-sensitive area.
 
-Site-center pitch/origin are explicit facts and are never derived from
-NativeImageRaster. The rectangle, when resolved, is a geometric sensitive
-region only. It does not include microlens redirection, charge diffusion,
-electrical crosstalk, QE, throughput, spectral response, or an effective
-radiometric collection area.
+Site pitch and origin are declared facts, never derived from NativeImageRaster.
+The rectangle, when given, is a geometric sensitive region only. It does not
+include microlens effects, charge diffusion, electrical crosstalk, QE,
+throughput, spectral response or an effective light-collection area.
 
 ```ts
 export function parseSensorSamplingApertureProfile(
@@ -93,7 +92,7 @@ export interface ResolvedSensorSamplingAperture {
       "none-by-model";
   };
   /**
-   * Hard scientific boundaries.
+   * Fixed statements of what this result does not establish.
    */
   sitePitchDerivedFromNativeImageRaster: false;
   apertureDerivedFromSitePitch: false;
@@ -116,12 +115,12 @@ export interface ResolvedSensorSamplingAperture {
 
 ## resolveSensorSamplingAperture
 
-Resolves one geometric sampling aperture in native sensor physical space.
+Resolves one site's geometric sampling aperture in native sensor physical space.
 
-The result provides a normalized uniform-area spatial averaging footprint for
-future image sampling, plus its geometric physical area/fill-fraction
-diagnostics. It deliberately does not promote that geometric area into
-radiometric collection efficiency or physical photodiode truth.
+The result is a normalized footprint that averages evenly over its area, for
+image sampling, plus its physical area and fill fraction. That geometric area
+is deliberately not treated as light-collection efficiency or as the true
+photodiode shape.
 
 ```ts
 export function resolveSensorSamplingAperture(
@@ -154,19 +153,18 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SensorGeometricSensitiveAperture =
   | {
       /**
-       * The physical/light-sensitive spatial aperture is known to matter but
-       * its geometry is not defensibly resolved.
+       * The light-sensitive area is known to matter, but its shape is not
+       * known well enough to use.
        */
       kind: "unresolved";
       evidence: readonly EvidenceProvenance[];
     }
   | {
       /**
-       * First geometric sensitive-region approximation.
+       * A simple approximation of the sensitive area as a rectangle.
        *
-       * This rectangle is constrained to remain inside one regular lattice
-       * cell, so neighboring geometric sensitive regions do not overlap in
-       * schema 0.1.0.
+       * The rectangle must stay inside one grid cell, so neighbouring
+       * sensitive areas never overlap in schema 0.1.0.
        */
       kind: "uniform-axis-aligned-rectangle";
       widthMicrometers: number;
@@ -203,14 +201,13 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorSiteCenterLatticeRegistration {
   kind: "regular-rectangular-site-center-lattice";
   coordinateSystem: "native-sensor-physical";
-  /** Horizontal site-center pitch in micrometres. */
+  /** Horizontal centre-to-centre site spacing (pitch) in micrometres. */
   pitchXMicrometers: number;
-  /** Vertical site-center pitch in micrometres. */
+  /** Vertical centre-to-centre site spacing (pitch) in micrometres. */
   pitchYMicrometers: number;
   /**
-   * First site center relative to the imaging area's physical top-left edge.
-   *
-   * +X right, +Y down. Units: micrometres.
+   * Centre of the first site, measured from the imaging area's physical
+   * top-left corner. +X right, +Y down. Units: micrometres.
    */
   firstSiteCenterFromImagingAreaTopLeftMicrometers: {
     x: number;

package/docs/api/sensor-scene-eqe-temporal-exposure.md

@@ -1,12 +1,13 @@
 # sensor/scene-eqe-temporal-exposure.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.
 
 ## calculateSceneSensorEqeTemporalExposure
 
-Compose declared scene radiance through paraxial optics and instantaneous EQE
-at every exact local shutter midpoint. Light is never averaged before response
-validity. No projection, renderer, PSF, charge/noise or production stage executes.
+Runs declared scene radiance through paraxial optics and the instantaneous EQE
+response at every exact local shutter midpoint time. Light is never averaged
+before the response checks. No projection, renderer, PSF, charge, noise or
+production stage runs.
 
 ```ts
 export function calculateSceneSensorEqeTemporalExposure(
@@ -18,15 +19,15 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CalculateSceneSensorEqeTemporalExposureInput
 
-Declared physical scene radiance at every spatial/wavelength/local-shutter midpoint.
+Input: declared physical scene radiance at every spatial position, wavelength and local shutter midpoint time.
 
 ```ts
 export interface CalculateSceneSensorEqeTemporalExposureInput {
-  /** One destination site, response and local shutter event; no stationarity declaration. */
+  /** One destination site, its response and one local shutter event. No constant-rate declaration is needed. */
   sensor: Omit<CalculateSensorEqeTemporalExposureInput, "samples">;
   sceneBindings: CalculateSceneToSensorIrradianceQuadratureInput["sceneBindings"];
   optics: CalculateSceneToSensorIrradianceQuadratureInput["optics"];
-  /** Explicitly binds scene query seconds to the shutter's first-opening boundary. */
+  /** States that scene query times are seconds from the shutter's first opening boundary. */
   timeReference: "first-opening-boundary-phase";
   samples: readonly {
     temporalSampleIndex: number;
@@ -38,7 +39,7 @@ export interface CalculateSceneSensorEqeTemporalExposureInput {
 
 ## SceneSensorEqeTemporalExposure
 
-Child optical and sensor envelopes retain approximation/evidence independently.
+Result. The optical and sensor results each keep their own approximation labels and evidence.
 
 ```ts
 export interface SceneSensorEqeTemporalExposure {

package/docs/api/sensor-sensor-geometry.md

@@ -1,14 +1,13 @@
 # sensor/sensor-geometry.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.
 
 ## calculateImagingAreaMetrics
 
-Calculates physical imaging-area metrics independently from native raster
-density.
+Calculates metrics of the physical imaging area, independent of pixel count.
 
-Crop factor uses the diagonal ratio to a 36 × 24 mm reference frame.
-Digital/output crops are not part of this physical imaging-area quantity.
+Crop factor is the ratio of diagonals to a 36 × 24 mm reference frame. It
+does not include any digital or output crop.
 
 ```ts
 export function calculateImagingAreaMetrics(
@@ -20,12 +19,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateSensorGeometryMetrics
 
-Calculates physical imaging-area, native-raster, and geometric sampling
-metrics without coupling sensor size to resolution.
+Calculates metrics of the physical imaging area, the native pixel grid and
+the sample spacing, keeping sensor size and resolution independent.
 
-The supplied raster is assumed to span the supplied imaging area. Derived
-sampling pitch is geometric sample spacing only and must not be interpreted
-as photosite fill factor or photon-collection area.
+The grid is assumed to cover the whole imaging area. The derived pitch is
+only the spacing between samples. Do not read it as the photosite's fill
+factor or light-collecting area.
 
 ```ts
 export function calculateSensorGeometryMetrics(
@@ -59,8 +58,8 @@ export interface ImagingAreaMetrics {
   /**
    * Diagonal crop factor relative to a 36 × 24 mm reference frame.
    *
-   * This is a physical imaging-area quantity and does not include later
-   * digital/output cropping.
+   * It describes the physical imaging area only, and does not include any
+   * later digital or output crop.
    */
   cropFactor35Mm: number;
 }
@@ -68,10 +67,10 @@ export interface ImagingAreaMetrics {
 
 ## NativeImageRaster
 
-Native effective image-sampling raster associated with an imaging area.
+The native pixel grid of an imaging area.
 
-This alias identifies semantic role; generic active/output rasters should
-use RasterDimensions instead.
+This alias names the role. For other grids, such as active or output
+images, use RasterDimensions.
 
 ```ts
 export type NativeImageRaster = RasterDimensions;
@@ -79,10 +78,10 @@ export type NativeImageRaster = RasterDimensions;
 
 ## RasterDimensions
 
-Native effective image-sampling raster associated with an imaging area.
+Width and height of an image grid in pixels.
 
-The raster describes effective image samples. It does not imply that each
-sample corresponds one-to-one with a physical photodiode/photosite.
+Pixels here are image samples. That does not mean each sample matches one
+physical photodiode (photosite).
 
 ```ts
 export interface RasterDimensions {
@@ -110,15 +109,15 @@ export interface SensorGeometryMetrics {
   };
   sampling: {
     /**
-     * Horizontal geometric sampling pitch in micrometres.
+     * Horizontal sample spacing (pitch) in micrometres.
      *
-     * This is image-sample spacing, not physical photodiode active area.
+     * This is the spacing between image samples, not the photodiode's active area.
      */
     pitchXMicrometers: number;
     /**
-     * Vertical geometric sampling pitch in micrometres.
+     * Vertical sample spacing (pitch) in micrometres.
      *
-     * This is image-sample spacing, not physical photodiode active area.
+     * This is the spacing between image samples, not the photodiode's active area.
      */
     pitchYMicrometers: number;
     /** Horizontal sampling pitch divided by vertical sampling pitch. */
@@ -129,9 +128,9 @@ export interface SensorGeometryMetrics {
 
 ## SensorImagingArea
 
-Physical photosensitive imaging area used for image formation.
+The physical light-sensitive imaging area used for image formation.
 
-This is deliberately not a sensor package/die dimension.
+It is deliberately not the size of the sensor package or die.
 
 ```ts
 export interface SensorImagingArea {

package/docs/api/sensor-signal-noise.md

@@ -1,13 +1,13 @@
 # sensor/signal-noise.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.
 
 ## calculatePhotoelectrons
 
-Converts mean incident photon count to mean photoelectron count.
+Converts the mean incident photon count to the mean photoelectron count.
 
-This is an expectation value; the stochastic shot-noise realization is not
-generated by this deterministic calculation.
+This is an expected value. This deterministic calculation does not generate
+random shot noise.
 
 ```ts
 export function calculatePhotoelectrons(
@@ -23,7 +23,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface CalculatePhotoelectronsInput {
-  /** Mean photons incident on the photosite/measurement region. */
+  /** Mean number of photons reaching the photosite (or measurement region). */
   incidentPhotons: number;
   /** Quantum efficiency from 0 to 1 inclusive. */
   quantumEfficiency: number;
@@ -32,12 +32,12 @@ export interface CalculatePhotoelectronsInput {
 
 ## calculateSignalToNoise
 
-Calculates expected SNR from Poisson shot noise and independent RMS read
+Calculates the expected SNR from Poisson shot noise and independent RMS read
 noise.
 
-Variances are combined as signalElectrons + readNoiseElectrons^2.
-Dark current, fixed-pattern noise, quantization, clipping, and downstream
-processing are intentionally outside this primitive.
+Variances add: total variance = signalElectrons + readNoiseElectrons^2.
+Dark current, fixed-pattern noise, quantization, clipping and later
+processing are deliberately left out.
 
 ```ts
 export function calculateSignalToNoise(
@@ -69,7 +69,7 @@ export interface SignalToNoise {
   shotNoiseStdElectrons: number;
   combinedNoiseStdElectrons: number;
   snrLinear: number;
-  /** Null when the signal is zero because -Infinity dB is not JSON-safe. */
+  /** Null when the signal is zero, because -Infinity dB cannot be stored in JSON. */
   snrDb: number | null;
 }
 ```

package/docs/api/sensor-spatial-sample-reduction.md

@@ -1,26 +1,25 @@
 # sensor/spatial-sample-reduction.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.
 
 ## reduceSensorSpatialSamplingQuadrature
 
-Reduces explicitly identified nonnegative linear scalar values over a
+Combines nonnegative linear values, each tagged with its node, over a
 validated sensor spatial quadrature.
 
-This function does not sample a renderer or optical model itself. Callers
-evaluate one value at every quadrature node's preAntiAliasingSourcePointMm
-and provide those values with exact node identity. Ordering is deliberately
-irrelevant.
+It does not sample a renderer or optical model itself. Callers evaluate one
+value at every node's preAntiAliasingSourcePointMm and pass the values with
+their exact node identity. Order does not matter.
 
-Two domains are supported:
+Two value domains are supported:
 
-- relative-linear: dimensionless nonnegative irradiance-like proxy for
-  deterministic renderer/science regression;
-- radiometric-irradiance: physical sensor-plane irradiance in W/m^2.
+- relative-linear: a dimensionless, nonnegative stand-in for irradiance, for
+  deterministic renderer and science regression tests;
+- radiometric-irradiance: physical irradiance on the sensor plane in W/m^2.
 
-The destination site's channelId is metadata only. No CFA spectral
-transmittance/sensitivity is applied, so the output must not be called a
-physically color-filtered mosaic sample or RAW value.
+The destination site's channelId is a label only. No CFA spectral
+transmittance or sensitivity is applied, so do not call the output a
+colour-filtered mosaic sample or a RAW value.
 
 ```ts
 export function reduceSensorSpatialSamplingQuadrature(
@@ -39,9 +38,9 @@ export interface ReduceSensorSpatialSamplingQuadratureInput {
   quadrature: SensorSpatialSamplingQuadrature;
   valueDomain: SensorSpatialSampleValueDomain;
   /**
-   * Exactly one explicitly identified value per quadrature node.
+   * Exactly one value per quadrature node, each with its node identity.
    *
-   * Ordering is not significant; node identity is.
+   * Order does not matter; the node identity does.
    */
   nodeValues: readonly SensorSpatialQuadratureNodeValue[];
 }
@@ -67,10 +66,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorSpatialQuadratureNodeValue {
   node: SensorSpatialQuadratureNodeIdentity;
   /**
-   * Nonnegative finite scalar in the declared value domain.
+   * A nonnegative, finite number in the declared value domain.
    *
-   * Values are evaluated at the corresponding quadrature node's
-   * preAntiAliasingSourcePointMm.
+   * It is evaluated at the matching node's preAntiAliasingSourcePointMm.
    */
   value: number;
 }
@@ -87,9 +85,9 @@ export interface SensorSpatialSampleReduction {
     y: number;
   };
   /**
-   * Semantic destination CFA/color-site label only.
+   * Label of the destination CFA (colour filter array) site only.
    *
-   * No spectral filter response is applied by this reducer.
+   * This reducer applies no spectral filter response.
    */
   channelId: string;
   outputMeaning:
@@ -134,13 +132,13 @@ export type SensorSpatialSampleReductionValue =
       semantic:
         "nonnegative-sensor-plane-irradiance-proxy";
       /**
-       * Dimensionless weighted spatial average in the same relative domain.
+       * Weighted spatial average (dimensionless), in the same relative domain.
        */
       normalizedSpatialAverageRelative: number;
       /**
        * Relative value × square micrometres.
        *
-       * This is a geometric area-weighted diagnostic, not radiometric power.
+       * A geometric, area-weighted diagnostic, not a radiometric power.
        */
       geometricAreaIntegralRelativeSquareMicrometers: number;
     }
@@ -149,18 +147,17 @@ export type SensorSpatialSampleReductionValue =
       unit: "W/m^2";
       semantic: "sensor-plane-irradiance";
       /**
-       * Weighted mean irradiance over the geometric aperture after applying
-       * the declared normalized AA spatial redistribution.
+       * Weighted mean irradiance over the geometric aperture, after the
+       * declared normalized AA spreading.
        */
       normalizedSpatialAverageIrradianceWattsPerSquareMeter: number;
       /**
-       * Incident radiant flux represented by integrating the supplied
-       * irradiance over the geometric aperture under the declared normalized
-       * AA redistribution. Units: watts.
+       * Incident radiant flux: the supplied irradiance integrated over the
+       * geometric aperture, with the declared normalized AA spreading.
+       * Units: watts.
        *
-       * This remains pre-CFA-response, pre-QE, pre-microlens-response and
-       * excludes any optical-stack throughput not already present in the
-       * caller-supplied irradiance values.
+       * It is before any CFA response, QE or microlens response, and excludes
+       * any optical-stack throughput not already in the caller's irradiance values.
        */
       geometricApertureIncidentFluxWatts: number;
     };

package/docs/api/sensor-spatial-sampling-quadrature.md

@@ -1,36 +1,34 @@
 # sensor/spatial-sampling-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.
 
 ## calculateSensorSpatialSamplingQuadrature
 
-Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+Builds the deterministic spatial sample points (quadrature nodes) for one CFA
+(colour filter array) site.
 
-The quadrature composes:
+It combines:
 
-1. the resolved geometric sensitive aperture from the sampling-aperture
-   foundation; and
-2. the resolved effective AA point-splitting kernel from the optical-stack
-   foundation.
+1. the site's geometric light-sensitive aperture (from sampling-aperture); and
+2. the anti-aliasing (AA) point-splitting kernel (from optical-stack).
 
-The first aperture integration uses a tensor-product uniform midpoint rule.
-For an AA component that moves optical energy by +delta on the sensor plane,
-a destination aperture point samples the pre-AA optical field at
-destination - delta. This inverse-source convention prevents applying the AA
-shift twice.
+The aperture is integrated with a grid of evenly spaced midpoints (a
+tensor-product midpoint rule). If an AA component moves light by +delta on
+the sensor, a destination point samples the light field before AA at
+destination − delta. Working backwards like this means the shift is never
+applied twice.
 
-The destination sensor site's CFA channel applies to every node. The
-pre-AA source coordinate is an optical-field location, not another CFA site;
-therefore shifted source coordinates never reassign the destination channel.
+The destination site's CFA channel applies to every node. The pre-AA source
+point is a position in the light field, not another CFA site, so a shifted
+source point never changes the destination channel.
 
-Nodes whose pre-AA source coordinates fall outside the active imaging area
-are retained. They are neither clamped nor dropped/renormalized. A renderer
-or optical-field provider owns source-coverage policy.
+Nodes whose pre-AA source point falls outside the active imaging area are
+kept. They are neither clamped nor dropped (and weights are not
+renormalized). The renderer or light-field provider decides how to cover them.
 
-normalized weights approximate a spatial average. Square-micrometre measures
-approximate a geometric area integral. Neither includes radiometric
-throughput, QE, photon conversion, microlenses, diffusion/crosstalk, or
-temporal integration.
+Normalized weights approximate a spatial average. Square-micrometre measures
+approximate a geometric area integral. Neither includes throughput, QE,
+photon conversion, microlenses, diffusion, crosstalk or integration over time.
 
 ```ts
 export function calculateSensorSpatialSamplingQuadrature(
@@ -93,7 +91,7 @@ export interface SensorSpatialSamplingQuadrature {
   sourceCoveragePolicy: "not-applied";
   nodes: readonly SensorSpatialSamplingQuadratureNode[];
   /**
-   * Hard scientific boundaries.
+   * Fixed statements of what this result does not include.
    */
   opticalFieldValuesIncluded: false;
   radianceIncluded: false;
@@ -129,17 +127,17 @@ export interface SensorSpatialSamplingQuadratureNode {
   apertureSampleXIndex: number;
   apertureSampleYIndex: number;
   /**
-   * Destination point inside the geometric sensitive aperture after the
-   * declared AA point-splitting response.
+   * Destination point inside the geometric sensitive aperture, after the
+   * declared AA point splitting.
    *
-   * Native sensor physical coordinates, millimetres from the optical axis.
+   * Native sensor physical coordinates, in millimetres from the optical axis.
    */
   destinationAperturePointMm: {
     x: number;
     y: number;
   };
   /**
-   * Declared AA displacement of optical energy on the sensor plane.
+   * How far the declared AA component moves light on the sensor plane.
    *
    * +X right, +Y down; micrometres.
    */
@@ -148,8 +146,8 @@ export interface SensorSpatialSamplingQuadratureNode {
     y: number;
   };
   /**
-   * Pre-AA source point that maps to destinationAperturePointMm under the
-   * declared split component:
+   * The point in the light field before AA that lands on
+   * destinationAperturePointMm through this split component:
    *
    * source = destination - AA offset
    */
@@ -158,9 +156,9 @@ export interface SensorSpatialSamplingQuadratureNode {
     y: number;
   };
   /**
-   * Whether the pre-AA source point lies inside the active physical imaging
-   * area. False is not an error; downstream source-coverage policy decides how
-   * to handle valid optical support outside the active sampling area.
+   * Whether the pre-AA source point is inside the active physical imaging
+   * area. False is not an error; downstream code decides how to handle valid
+   * light from outside the active sampling area.
    */
   preAntiAliasingSourceInsideImagingArea: boolean;
   /** Dimensionless midpoint weight for the aperture-area average. */
@@ -168,20 +166,20 @@ export interface SensorSpatialSamplingQuadratureNode {
   /** Dimensionless normalized weight from the AA split component. */
   normalizedAntiAliasingWeight: number;
   /**
-   * Dimensionless product used for a spatial average of a downstream optical
-   * field under this quadrature approximation.
+   * Product of the two weights (dimensionless), used to average a light field
+   * over the site with this quadrature.
    */
   combinedNormalizedSpatialWeight: number;
   /**
-   * Geometric area measure represented by this aperture midpoint before the
-   * AA component weight is applied. Units: square micrometres.
+   * Geometric area this aperture midpoint stands for, before the AA component
+   * weight is applied. Units: square micrometres.
    */
   apertureAreaMeasureSquareMicrometers: number;
   /**
-   * Geometric area measure multiplied by the dimensionless AA component
-   * weight. Units remain square micrometres.
+   * Geometric area multiplied by the (dimensionless) AA component weight.
+   * Units are still square micrometres.
    *
-   * This is not an effective radiometric collection area.
+   * This is not an effective light-collection area.
    */
   combinedAreaMeasureSquareMicrometers: number;
 }