@photivra/engine 1.4.0 → 2.0.0

package/docs/api/sensor-readout-timing.md

@@ -1,23 +1,23 @@
 # sensor/readout-timing.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## calculateSensorReadoutTiming
 
-Resolves a capture-specific native sensor readout scan schedule.
+Resolves the sensor readout scan schedule for one capture.
 
-Rolling readout uses a uniform-linear single-axis approximation across the
-declared active capture. The caller supplies the spatial timing span
-explicitly; it is never inferred from total data-readout duration, active
-crop dimensions, native raster density, output resolution, sensor
-architecture metadata, or shutter mechanism.
+Rolling readout is modelled as a uniform linear scan along one axis of the
+declared active capture. The caller supplies the scan's time span (skew)
+explicitly. It is never worked out from the total data-readout time, crop
+size, pixel density, output resolution, sensor-architecture metadata or the
+shutter mechanism.
 
-Global readout has no spatial phase skew in this model even when a non-zero
-data-readout duration is declared.
+Global readout has no skew in this model, even when a non-zero data-readout
+time is declared.
 
-This foundation does not define local exposure start/end times, mechanical
-curtain travel, EFCS curtain behavior, rolling-shutter image distortion,
-flash/flicker interactions, or motion integration.
+Not covered: local exposure start and end times, mechanical curtain travel,
+EFCS (electronic first-curtain shutter) behaviour, rolling-shutter image
+distortion, flash or flicker, and motion integration.
 
 ```ts
 export function calculateSensorReadoutTiming(
@@ -35,23 +35,23 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CalculateSensorReadoutTimingInput {
   nativeRaster: NativeImageRaster;
   /**
-   * Active capture rectangle in invariant native raster coordinates.
+   * Active capture rectangle, in fixed native pixel coordinates.
    *
-   * Defaults to the complete native raster. Timing is never inferred by
-   * scaling a full-frame value to this rectangle.
+   * Defaults to the whole native image. Timing is never worked out by scaling
+   * a full-frame value to this rectangle.
    */
   activeCaptureRect?: RasterRect;
   /**
-   * Selected shutter mechanism for the capture.
+   * The shutter mechanism chosen for the capture.
    *
-   * It is reported independently and does not modify the sensor timing
-   * schedule in this foundation.
+   * It is reported separately and does not change the sensor readout timing
+   * in this model.
    */
   shutterMechanism: CaptureShutterMechanism;
   readout: SensorReadoutTimingDeclaration;
   /**
-   * Optional continuous native raster edge-coordinate points for timing
-   * diagnostics. Pixel centers may be represented with +0.5 offsets.
+   * Optional points, in continuous native pixel coordinates measured from pixel
+   * edges, to report timing for. A pixel centre is at +0.5.
    */
   samplePointsNative?: readonly RasterPoint[];
 }
@@ -76,9 +76,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface GlobalSensorReadoutTimingDeclaration {
   readoutMode: "global";
   /**
-   * Capture-specific sensor data-readout duration.
+   * Sensor data-readout time for this capture.
    *
-   * This is deliberately not interpreted as spatial exposure/readout skew.
+   * It is deliberately not treated as the spatial exposure or readout skew.
    */
   captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
   scanDirectionNative?: never;
@@ -106,11 +106,10 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface RollingSensorReadoutTimingDeclaration {
   readoutMode: "rolling";
   /**
-   * Capture-specific sensor data-readout duration.
+   * Sensor data-readout time for this capture.
    *
-   * This fact is retained independently from spatial sampling skew because
-   * published/declared readout duration and the spatial timing span need not be
-   * treated as the same quantity.
+   * It is kept separate from the spatial skew, because a published readout time
+   * and the scan's time span are not necessarily the same quantity.
    */
   captureReadoutDurationSeconds: SourcedSensorTimingSeconds;
   /**
@@ -118,8 +117,8 @@ export interface RollingSensorReadoutTimingDeclaration {
    */
   scanDirectionNative: SourcedSensorReadoutFact<NativeSensorReadoutScanDirection>;
   /**
-   * Time difference between the first and last spatial scan positions in the
-   * uniform-linear timing approximation.
+   * Time between the first and last scan positions, in the uniform linear
+   * timing approximation (the readout skew).
    */
   spatialSamplingSkewSeconds: SourcedSensorTimingSeconds;
 }
@@ -127,11 +126,11 @@ export interface RollingSensorReadoutTimingDeclaration {
 
 ## SensorReadoutMode
 
-Readout architecture selected for one capture.
+The readout mode chosen for one capture.
 
-This reuses the architecture vocabulary but is not a hardware-capability
-assertion. SensorArchitectureProfile.readoutCapabilities remains descriptive
-metadata and is not consulted automatically.
+It uses the same names as the architecture metadata, but does not claim the
+hardware supports it. SensorArchitectureProfile.readoutCapabilities is
+descriptive only and is not checked automatically.
 
 ```ts
 export type SensorReadoutMode = SensorReadoutArchitecture;
@@ -180,10 +179,9 @@ export interface SensorReadoutTimingSample {
   pointNative: RasterPoint;
   normalizedScanPosition: number | null;
   /**
-   * Relative native-sensor readout phase in seconds.
+   * Readout time of this point, in seconds, relative to the first scan position (0).
    *
-   * Zero is the first spatial scan position. This is not automatically an
-   * exposure-start time or shutter-curtain time.
+   * It is not automatically an exposure-start time or a shutter-curtain time.
    */
   readoutPhaseOffsetSeconds: number;
 }

package/docs/api/sensor-response-application-compatibility.md

@@ -1,15 +1,14 @@
 # sensor/response-application-compatibility.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## assessSensorResponseApplicationCompatibility
 
-Assess whether exact source-plane, area, profile/channel and reference-condition bindings permit the
-selected response application path.
+Checks whether the source plane, area, profile, channel and reference conditions allow the
+selected way of applying the response.
 
-Response application checks exact profile/channel, source plane, incident-area basis, spatial
-uniformity and reference conditions. Structural compatibility alone does not authorize signal
-conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+Passing this alone does not allow converting light to signal. The per-bin operating-range check
+and the EQE or A/W conversion are separate steps.
 
 ```ts
 export function assessSensorResponseApplicationCompatibility(
@@ -39,12 +38,11 @@ export interface AssessSensorResponseApplicationCompatibilityInput {
 
 ## parseSensorResponseApplicationProfile
 
-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.
 
-Response application checks exact profile/channel, source plane, incident-area basis, spatial
-uniformity and reference conditions. Structural compatibility alone does not authorize signal
-conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+The profile states the source plane, incident-area basis, spatial uniformity and reference
+conditions under which a response applies.
 
 ```ts
 export function parseSensorResponseApplicationProfile(

package/docs/api/sensor-response-operating-range.md

@@ -1,16 +1,14 @@
 # sensor/response-operating-range.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
 
 ## assessSensorResponseOperatingRange
 
-Assess every declared spectral-bin input against operating applicability and superposition before
-authorizing instantaneous response conversion.
+Checks every declared spectral-bin input against the operating range and the superposition
+requirement, before any instantaneous response conversion is allowed.
 
-Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
-conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
-applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
-local sub-aperture.
+Each bin must be in range, and spatial linear superposition must hold. A valid average must not
+hide a part of the aperture that is too bright.
 
 ```ts
 export function assessSensorResponseOperatingRange(
@@ -38,13 +36,11 @@ export interface AssessSensorResponseOperatingRangeInput {
 
 ## parseSensorResponseOperatingRangeProfile
 
-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.
 
-Operating-range assessment preserves incident power versus irradiance, wavelength support, reference
-conditions and declared nonlinearity criterion. Per-bin conversion requires spectral-bin
-applicability and spatial linear superposition. Valid mean input must not conceal an invalid bright
-local sub-aperture.
+The profile states the input quantity (incident power or irradiance), wavelength coverage,
+reference conditions and non-linearity criterion of the calibrated operating range.
 
 ```ts
 export function parseSensorResponseOperatingRangeProfile(
@@ -219,15 +215,15 @@ export interface SensorResponseOperatingRangeProfile {
   linearityCriterion:
     SensorResponseLinearityCriterion;
   /**
-   * Optional for backward compatibility. Omission parses as not-established
-   * and blocks new response-rate authorization.
+   * Optional for backward compatibility. If omitted, it parses as "not
+   * established", which blocks new response-rate conversions.
    */
   spatialLinearityModel?:
     SensorResponseOperatingSpatialLinearityModel;
   /**
-   * Optional for backward compatibility. Omission means the calibration only
-   * establishes a broadband-integrated operating range and cannot authorize
-   * wavelength-by-wavelength response conversion.
+   * Optional for backward compatibility. If omitted, the calibration only
+   * establishes an operating range for broadband (wavelength-integrated) input,
+   * and cannot allow wavelength-by-wavelength response conversion.
    */
   spectralInputModel?:
     SensorResponseOperatingSpectralInputModel;

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

@@ -1,15 +1,14 @@
 # sensor/responsivity-photocurrent.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.4.0**, root API **1.4.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.4.0**, root API **1.4.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.4.0**, root API **1.4.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.4.0**, root API **1.4.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;
 }
 ```