@photivra/engine 1.3.0 → 1.4.0

package/docs/api/optics-scene-to-sensor-irradiance.md

@@ -1,6 +1,6 @@
 # optics/scene-to-sensor-irradiance.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSceneRadianceToSensorIrradiance
 

package/docs/api/optics-scene-to-sensor-quadrature.md

@@ -1,6 +1,6 @@
 # optics/scene-to-sensor-quadrature.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSceneToSensorIrradianceQuadrature
 

package/docs/api/optics-sensor-aperture-rays.md

@@ -0,0 +1,75 @@
+# optics/sensor-aperture-rays.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.
+
+## calculateSensorApertureRays
+
+Uniform-area polar midpoint rule, normalized as an average, never a second f-number factor.
+
+```ts
+export function calculateSensorApertureRays(input: CalculateSensorApertureRaysInput): CalculationResult<SensorApertureRays>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorApertureRaysInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorApertureRaysInput {
+  sourcePointNativeSensorMm: { x: number; y: number };
+  focalLengthMm: number;
+  nominalFNumber: number;
+  focus: FocusPlane;
+  pupil: IdealCircularPupil;
+  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+  timeSecondsFromOpeningReference: number;
+}
+```
+
+## IdealCircularPupil
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IdealCircularPupil {
+  kind: "ideal-uniform-circular-pupil";
+  radialSampleCount: number;
+  angularSampleCount: number;
+  evidence: readonly EvidenceProvenance[];
+  limitation: string;
+}
+```
+
+## SensorApertureRay
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorApertureRay {
+  /** Lens principal-plane origin and look direction in exposure-opening camera axes. */
+  originM: { x: number; y: number; z: number };
+  directionUnitVector: { x: number; y: number; z: number };
+  pupilPointMm: { x: number; y: number };
+  weight: number;
+  pupilSampleIndex: number;
+}
+```
+
+## SensorApertureRays
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorApertureRays {
+  rays: readonly SensorApertureRay[];
+  projectionDistanceMm: number;
+  pupilRadiusMm: number;
+  focus: FocusPlane;
+  pupil: IdealCircularPupil;
+  sceneVisibilityCalculated: false;
+  radiometryCalculated: false;
+  apertureAreaApplied: false;
+}
+```

package/docs/api/optics-sensor-environment-query.md

@@ -1,6 +1,6 @@
 # optics/sensor-environment-query.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorEnvironmentRadianceQuery
 

package/docs/api/optics-sensor-psf-quadrature.md

@@ -1,6 +1,6 @@
 # optics/sensor-psf-quadrature.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorPsfIrradianceQuadrature
 

package/docs/api/optics-stray-light.md

@@ -1,6 +1,6 @@
 # optics/stray-light.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateLensStrayLightIrradiance
 

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

@@ -1,6 +1,6 @@
 # optics/thin-lens.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateThinLensImageDistance
 

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

@@ -1,6 +1,6 @@
 # output/capture-corrected-sdr.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateCaptureCorrectedSdr
 

package/docs/api/output-capture-geometry.md

@@ -1,6 +1,6 @@
 # output/capture-geometry.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## ActiveCaptureFieldOfView
 

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

@@ -1,6 +1,6 @@
 # output/capture-sdr.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateCaptureSdr
 

package/docs/api/output-crop.md

@@ -1,6 +1,6 @@
 # output/crop.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateCenteredCrop
 

package/docs/api/output-geometric-transforms.md

@@ -1,6 +1,6 @@
 # output/geometric-transforms.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## AffineGeometricTransform
 

package/docs/api/output-lens-corrections.md

@@ -1,6 +1,6 @@
 # output/lens-corrections.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateLensCorrectedCapture
 

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

@@ -1,6 +1,6 @@
 # output/native-capture-sdr.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateNativeCaptureSdrPlan
 

package/docs/api/output-print-contrast-reference.md

@@ -1,6 +1,6 @@
 # output/print-contrast-reference.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculatePrintContrastReference
 

package/docs/api/output-print-detail.md

@@ -1,6 +1,6 @@
 # output/print-detail.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculatePrintRegionDetail
 

package/docs/api/output-print-jpeg.md

@@ -0,0 +1,117 @@
+# output/print-jpeg.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.
+
+## createPrintJpegTask
+
+Filtering uses exact source-pixel area overlap after decoding the explicitly declared 8-bit SDR stage.
+
+```ts
+export function createPrintJpegTask(input:PrintJpegInput,provider:PrintJpegProvider):PrintJpegTask;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parsePrintJpegInput
+
+Admission-only; source detail/perception/printer qualification are separate contracts.
+
+```ts
+export function parsePrintJpegInput(input:PrintJpegInput):PrintJpegInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PRINT_JPEG_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PRINT_JPEG_SCHEMA_VERSION="0.1.0" as const
+```
+
+## PrintJpegInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegInput {
+  source:PrintJpegSource;
+  /** Integer crop in the declared oriented output source, not crop-local sensor/CFA coordinates. */
+  crop:RasterRect;
+  outputWidth:number;outputHeight:number;
+  quantizationStep:number;
+  maximumEncodedBytes:number;
+  maximumProviderReads:number;
+}
+```
+
+## PrintJpegOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegOutput {
+  schemaVersion:typeof PRINT_JPEG_SCHEMA_VERSION;
+  input:PrintJpegInput;
+  mediaType:"image/jpeg";
+  bytes:Uint8Array;
+  iccProfileVersion:typeof SRGB_ICC_PROFILE_VERSION;
+  width:number;height:number;
+  resampling:"exact-area-average-in-decoded-linear-light";
+  sourceStage:"post-SDR-8-bit-quantization";
+  digitalUpscalingApplied:false;
+  sourceBytesVerified:false;
+  providerReads:number;
+}
+```
+
+## PrintJpegProvider
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegProvider {
+  readTile(request:Readonly<PrintJpegTileRequest>,signal:AbortSignal):Promise<PrintJpegTile>;
+  yieldControl(signal:AbortSignal):Promise<void>;
+}
+```
+
+## PrintJpegSource
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegSource {
+  captureId:string;imageStateId:string;artifactId:string;sha256:string;
+  width:number;height:number;
+  encoding:"encoded-srgb-8-rgb";
+}
+```
+
+## PrintJpegTask
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegTask {
+  readonly state:NativeRawTaskState;
+  run():Promise<void>;cancel():void;dispose():void;takeOutput():PrintJpegOutput;
+}
+```
+
+## PrintJpegTile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegTile extends PrintJpegTileRequest {samples:Uint8Array}
+```
+
+## PrintJpegTileRequest
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PrintJpegTileRequest {source:PrintJpegSource;x:number;y:number;width:number;height:number}
+```

package/docs/api/output-print-plan.md

@@ -1,6 +1,6 @@
 # output/print-plan.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculatePrintPlan
 

package/docs/api/output-print-region-statistics.md

@@ -1,6 +1,6 @@
 # output/print-region-statistics.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculatePrintRegionDifference
 

package/docs/api/output-sdr-rendering.md

@@ -1,6 +1,6 @@
 # output/sdr-rendering.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSdrRendering
 

package/docs/api/output-subject-framing-crop.md

@@ -1,6 +1,6 @@
 # output/subject-framing-crop.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSubjectFramingCrop
 

package/docs/api/schema-camera.md

@@ -1,6 +1,6 @@
 # schema/camera.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## CameraConfiguration
 

package/docs/api/schema-illumination-spectral.md

@@ -1,6 +1,6 @@
 # schema/illumination-spectral.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## createSceneIlluminationSpectralCoverageParticipant
 

package/docs/api/schema-illumination-temporal.md

@@ -1,6 +1,6 @@
 # schema/illumination-temporal.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## evaluateSceneIlluminationTemporalMultiplier
 

package/docs/api/schema-illumination.md

@@ -1,6 +1,6 @@
 # schema/illumination.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## parseSceneIlluminationProfile
 

package/docs/api/schema-scene-radiance-temporal.md

@@ -1,6 +1,6 @@
 # schema/scene-radiance-temporal.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## createSceneRadianceTemporalSamplingPlan
 

package/docs/api/schema-scene-radiance.md

@@ -1,6 +1,6 @@
 # schema/scene-radiance.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## assessSceneMaterialResponseFidelity
 

package/docs/api/schema-scene.md

@@ -1,6 +1,6 @@
 # schema/scene.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## SceneCapability
 

package/docs/api/schema-validation.md

@@ -1,6 +1,6 @@
 # schema/validation.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## parseCameraConfiguration
 

package/docs/api/sensor-accumulated-charge.md

@@ -1,6 +1,6 @@
 # sensor/accumulated-charge.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## composeSensorAccumulatedCharge
 

package/docs/api/sensor-architecture.md

@@ -1,6 +1,6 @@
 # sensor/architecture.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## parseSensorArchitectureProfile
 

package/docs/api/sensor-camera-saturation-capacity.md

@@ -1,6 +1,6 @@
 # sensor/camera-saturation-capacity.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## assessSensorCameraSaturationCapacity
 

package/docs/api/sensor-capture-color-sampling-binding.md

@@ -1,6 +1,6 @@
 # sensor/capture-color-sampling-binding.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## CaptureModeFullFrameSampleIndex
 

package/docs/api/sensor-capture-mode-timing.md

@@ -1,6 +1,6 @@
 # sensor/capture-mode-timing.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION
 

package/docs/api/sensor-capture-mode.md

@@ -1,6 +1,6 @@
 # sensor/capture-mode.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## CaptureModeAcquisition
 

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

@@ -1,6 +1,6 @@
 # sensor/color-sampling.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## LayeredColorSamplingLayout
 

package/docs/api/sensor-constant-rate-temporal-integration.md

@@ -1,6 +1,6 @@
 # sensor/constant-rate-temporal-integration.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## IntegrateStationarySensorRateInput
 

package/docs/api/sensor-dark-current.md

@@ -1,6 +1,6 @@
 # sensor/dark-current.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorDarkCurrentCharge
 

package/docs/api/sensor-environment-photo-signal.md

@@ -1,6 +1,6 @@
 # sensor/environment-photo-signal.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateEnvironmentSensorPhotoSignal
 
@@ -26,6 +26,8 @@ export interface CalculateEnvironmentSensorPhotoSignalInput {
   motion: Pick<CalculateSensorEnvironmentRadianceQueryInput,
     "angularVelocityRadPerSec" | "timeReference" | "environmentDirectionConvention">;
   temporalSampleCount: number;
+  /** Optional ideal geometric DOF/visibility support; cannot combine with a sampled PSF. */
+  pupil?: IdealCircularPupil;
   /** Explicit source-field attenuation, applied once before PSF redistribution. */
   fieldThroughput: { kind: "unity"; evidence: readonly EvidenceProvenance[]; limitation: string } | {
     kind: "radial-illumination-vignetting"; profile: IlluminationVignettingProfile;
@@ -36,9 +38,19 @@ export interface CalculateEnvironmentSensorPhotoSignalInput {
     configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
   };
   evaluateRadiance: EnvironmentRadianceEvaluator;
+  /** Required with pupil; origin-aware scene intersections cannot use direction-only code. */
+  evaluateApertureRadiance?: EnvironmentApertureRadianceEvaluator;
 }
 ```
 
+## EnvironmentApertureRadianceEvaluator
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type EnvironmentApertureRadianceEvaluator = (request: Readonly<SceneRadianceEvaluationRequest>, apertureRay: Readonly<SensorApertureRay>) => SceneRadianceEvaluationResult;
+```
+
 ## EnvironmentRadianceEvaluator
 
 Supplied synchronous code executes locally. Invocation does not prove physical transport.
@@ -64,6 +76,8 @@ export interface EnvironmentSensorPhotoSignal {
   fieldThroughputLimitation: string;
   psfOmission: { evidence: readonly EvidenceProvenance[]; limitation: string } | null;
   psfRedistributionApplied: boolean;
+  pupilIntegrationApplied: boolean;
+  pupilIntegrationProfile: IdealCircularPupil | null;
   photo: ReturnType<typeof createSensorEqeTemporalPhotoSignal>;
   instants: readonly {
     temporalSampleIndex: number;
@@ -74,6 +88,8 @@ export interface EnvironmentSensorPhotoSignal {
       result: SceneRadianceEvaluationResult;
       bindings: ReturnType<typeof validateSceneRadianceEvaluationBindings>;
       optics: ReturnType<typeof calculateSceneRadianceToSensorIrradiance>;
+      apertureRay?: SensorApertureRay;
+      apertureRequest?: SceneRadianceEvaluationRequest;
     }[];
   }[];
 }

package/docs/api/sensor-eqe-electron-rate.md

@@ -1,6 +1,6 @@
 # sensor/eqe-electron-rate.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorEqeElectronRate
 

package/docs/api/sensor-eqe-local-exposure.md

@@ -1,6 +1,6 @@
 # sensor/eqe-local-exposure.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorEqeLocalExposure
 

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

@@ -1,6 +1,6 @@
 # sensor/eqe-temporal-exposure.ts public contracts
 
-Package **1.3.0**, root API **1.3.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.
+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.
 
 ## calculateSensorEqeTemporalExposure