@photivra/engine 1.5.0 → 2.1.0

package/docs/api/sensor-spatio-spectral-reduction.md

@@ -1,28 +1,27 @@
 # sensor/spatio-spectral-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.
 
 ## reduceSensorSpatioSpectralIrradiance
 
-Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y)
-over the Cartesian product of an existing spatial quadrature and spectral
+Integrates supplied spectral irradiance on the sensor plane, E_lambda(x,y),
+over every combination of an existing spatial quadrature and spectral
 quadrature.
 
-The supplied density unit is W/m^2/nm and wavelengthMeasureNanometers is
-d-lambda in nm, so their direct product has units W/m^2. Do not convert
-d-lambda to metres unless the spectral-density denominator is converted
-consistently.
+Units: the density is in W/m^2/nm and wavelengthMeasureNanometers is dλ in
+nm, so their product is in W/m^2. Do not convert dλ to metres unless the
+density's per-nanometre unit is converted to match.
 
-Spatial area integration uses the spatial quadrature's geometric area
-measures converted from square micrometres to square metres. The result is
-geometric-aperture incident radiant flux only; geometric area is not upgraded
-to an effective radiometric collection area.
+Area integration uses the spatial quadrature's geometric area measures,
+converted from square micrometres to square metres. The result is the
+incident radiant flux on the geometric aperture only; geometric area is not
+treated as an effective light-collection area.
 
-This reducer deliberately stops before sensor response. The spectral plan was
-derived from a specific response channel so its support/knots are useful, but
-QE, A/W responsivity and channel-filter transmission are not applied here.
-Response-scope/source-plane matching therefore remains an explicit later
-composition step.
+It deliberately stops before the sensor response. The spectral plan comes
+from a specific response channel, so its wavelength range and breakpoints
+fit that channel, but QE, A/W responsivity and colour-filter transmission are
+not applied here. Matching the response's scope and source plane is a
+separate later step.
 
 ```ts
 export function reduceSensorSpatioSpectralIrradiance(
@@ -42,10 +41,10 @@ export interface ReduceSensorSpatioSpectralIrradianceInput {
   spatialQuadrature: SensorSpatialSamplingQuadrature;
   spectralQuadrature: SensorSpectralQuadrature;
   /**
-   * Exactly one explicitly identified E_lambda(x,y) value for every Cartesian
-   * product of spatial and spectral quadrature nodes.
+   * Exactly one E_lambda(x,y) value, with its node identity, for every
+   * combination of spatial node and spectral node.
    *
-   * Ordering is not significant; node identity is.
+   * Order does not matter; the node identity does.
    */
   sampleValues: readonly SensorSpatioSpectralIrradianceSample[];
 }
@@ -112,11 +111,11 @@ export interface SensorSpatioSpectralIrradianceReduction {
   wavelengthIntegratedSpatialAverageIrradianceWattsPerSquareMeter:
     number;
   /**
-   * Integral over the requested wavelength interval and geometric aperture
-   * area. Units: W.
+   * Integral over the requested wavelength interval and the geometric
+   * aperture area. Units: W.
    *
-   * This is pre-sensor-response incident radiant flux over the declared
-   * wavelength interval, not collected optical power or generated charge.
+   * This is the incident radiant flux before the sensor response, over the
+   * declared wavelength interval. It is not collected power or generated charge.
    */
   wavelengthIntegratedGeometricApertureIncidentFluxWatts:
     number;
@@ -158,8 +157,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface SensorSpatioSpectralIrradianceSample {
   node: SensorSpatioSpectralNodeIdentity;
   /**
-   * Spectral irradiance evaluated at the spatial quadrature node's
-   * preAntiAliasingSourcePointMm and this spectral node's wavelength.
+   * Spectral irradiance at the spatial node's preAntiAliasingSourcePointMm
+   * and this spectral node's wavelength.
    *
    * Units: W/m^2/nm.
    */
@@ -196,11 +195,10 @@ export interface SensorSpatioSpectralWavelengthReduction {
   normalizedSpatialAverageSpectralIrradianceWattsPerSquareMeterPerNanometer:
     number;
   /**
-   * Spectral radiant flux density incident over the geometric sensitive
-   * aperture after the declared normalized AA redistribution.
-   * Units: W/nm.
+   * Spectral radiant flux reaching the geometric sensitive aperture, after the
+   * declared normalized AA spreading. Units: W/nm.
    *
-   * This uses geometric area, not an established radiometric collection area.
+   * This uses geometric area, not an established light-collection area.
    */
   geometricApertureIncidentSpectralFluxWattsPerNanometer: number;
   /**

package/docs/api/sensor-spectral-coverage.md

@@ -1,14 +1,14 @@
 # sensor/spectral-coverage.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.
 
 ## createSensorSpectralCoverageParticipant
 
-Adapts one parsed sensor response channel into the shared continuous
-spectral-coverage contract.
+Converts one parsed sensor response channel into the shared continuous
+spectral-coverage format.
 
-This exposes support and interpolation knots only. It does not apply QE or
-A/W responsivity and does not establish scene/optics coverage.
+It gives only the wavelength range and interpolation breakpoints. It does not
+apply QE or A/W responsivity, and says nothing about scene or optics coverage.
 
 ```ts
 export function createSensorSpectralCoverageParticipant(

package/docs/api/sensor-spectral-quadrature.md

@@ -1,29 +1,27 @@
 # sensor/spectral-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.
 
 ## calculateSensorSpectralQuadrature
 
-Builds deterministic wavelength quadrature nodes for one exact sensor
-response channel without applying the response to a source spectrum.
+Builds deterministic wavelength sample points for one exact sensor response
+channel. It does not apply the response to any spectrum.
 
-The requested wavelength range must lie fully inside the response channel's
-declared usable range. Response-curve knots and optional caller-provided
-continuous-spectrum/optics breakpoints partition that range. Each segment is
-then subdivided so no midpoint subinterval exceeds
+The requested range must lie fully inside the channel's declared usable
+range. The response curve's breakpoints, plus any caller-supplied breakpoints
+from the source spectrum or optics, split that range into segments. Each
+segment is then subdivided so no midpoint subinterval is wider than
 maximumSubintervalWidthNanometers.
 
-wavelengthMeasureNanometers is d-lambda in nanometres. It is not a
-dimensionless response weight. Future integration must use a source spectral
-density expressed per nanometre or explicitly convert units before
-multiplying by this measure.
+wavelengthMeasureNanometers is dλ in nanometres, not a dimensionless response
+weight. Multiply it only by a spectral density per nanometre, or convert
+units explicitly first.
 
-This function deliberately does not apply QE or A/W responsivity. Those
-representations have different compatible downstream signal domains: QE is
-photon-to-electron efficiency, while A/W responsivity relates incident
-radiant power to electrical current. A later versioned composition must also
-match responseScope to the source plane and collection-area semantics before
-integrating any signal.
+QE and A/W responsivity are deliberately not applied. They lead to different
+signals: QE is photon-to-electron efficiency, while A/W responsivity relates
+incident radiant power to electrical current. A later step must also match
+responseScope to the source plane and collection area before integrating any
+signal.
 
 ```ts
 export function calculateSensorSpectralQuadrature(
@@ -45,27 +43,27 @@ export interface CalculateSensorSpectralQuadratureInput {
   channelId: string;
   wavelengthBasis: SpectralWavelengthBasis;
   /**
-   * Explicit wavelength interval to sample. This API validates the interval
-   * against sensor-response support only; it does not establish scene-spectrum
-   * or optical-transmission coverage.
+   * Wavelength interval to sample. It is checked only against the range the
+   * sensor response supports, not against scene-spectrum or optical-transmission
+   * coverage.
    */
   wavelengthRangeNanometers:
     SensorSpectralWavelengthRangeNanometers;
   /**
-   * Hard upper bound on each midpoint subinterval width.
+   * Strict upper limit on the width of each midpoint subinterval.
    *
-   * Response knots and optional additional breakpoints split the requested
-   * range first; each resulting segment is then subdivided until every
-   * subinterval is no wider than this value.
+   * Response breakpoints and any additional breakpoints split the requested
+   * range first. Each segment is then subdivided until every subinterval is
+   * no wider than this value.
    */
   maximumSubintervalWidthNanometers: number;
   /**
    * Optional strictly increasing wavelength breakpoints from other continuous
-   * spectral factors, such as scene spectral-density or optical-transmission
-   * interpolation knots. Values must lie strictly inside the requested range.
+   * spectral inputs, such as the interpolation points of a scene spectrum or of
+   * optical transmission. Values must be strictly inside the requested range.
    *
-   * These coordinates do not assert that those external factors are actually
-   * available or valid over the requested range.
+   * Passing them does not claim those other inputs are available or valid over
+   * the requested range.
    */
   additionalBreakpointsNanometers?:
     readonly number[];
@@ -103,7 +101,7 @@ export interface SensorSpectralQuadrature {
   segmentBoundarySource:
     "requested-range-plus-response-knots-plus-optional-additional-breakpoints";
   /**
-   * Ordered unique segment boundaries, including requested range endpoints.
+   * Sorted, unique segment boundaries, including the ends of the requested range.
    */
   segmentBoundariesNanometers:
     readonly number[];
@@ -122,7 +120,7 @@ export interface SensorSpectralQuadrature {
       readonly (readonly EvidenceProvenance[])[];
   };
   /**
-   * Hard scientific boundaries.
+   * Fixed statements of what this result does not include.
    */
   responseValuesIncluded: false;
   responseApplicationPerformed: false;
@@ -158,16 +156,16 @@ export interface SensorSpectralQuadratureNode {
    */
   wavelengthNanometers: number;
   /**
-   * d-lambda represented by this node. Units: nm.
+   * dλ (wavelength width) this node stands for. Units: nm.
    *
-   * This is wavelength measure only. It is not response-weighted throughput,
-   * photon count, radiant energy, current, or a dimensionless probability.
+   * It is only a wavelength width. It is not response-weighted throughput,
+   * a photon count, radiant energy, current or a dimensionless probability.
    */
   wavelengthMeasureNanometers: number;
   /**
-   * Dimensionless wavelength measure normalized by the requested range width.
+   * The wavelength width divided by the requested range width (dimensionless).
    *
-   * This may be useful for averages, but it is not a sensor-response weight.
+   * Useful for averages, but it is not a sensor-response weight.
    */
   normalizedWavelengthWeight: number;
 }

package/docs/api/sensor-spectral-response.md

@@ -1,6 +1,6 @@
 # sensor/spectral-response.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.
 
 ## EffectiveSensorResponseScope
 
@@ -14,12 +14,12 @@ export type EffectiveSensorResponseScope =
 
 ## parseSensorSpectralResponseProfile
 
-Parses reusable wavelength-dependent response data for semantic sensor
-channels without inferring response from channel names or CFA family.
+Parses wavelength-dependent response data for sensor channels. Responses are
+never guessed from channel names or the CFA type.
 
-Embedded multi-point curves require reusable-data or Photivra-owned evidence.
-Public/factual references without reuse permission may support metadata but
-cannot by themselves authorize copying numeric curve data into the engine.
+An embedded multi-point curve needs evidence that the data is reusable or
+owned by Photivra. A public reference without reuse permission can support
+metadata, but does not by itself allow copying numeric curve data into the engine.
 
 ```ts
 export function parseSensorSpectralResponseProfile(
@@ -108,11 +108,11 @@ export type ResolvedSensorSpectralResponseValue =
 
 ## resolveSensorSpectralResponseAtWavelength
 
-Public spectral-response resolver for untrusted/raw profile inputs.
+Public spectral-response lookup for untrusted, unparsed profiles.
 
-Profiles are parsed once here. Internal composition code that has already
-parsed both profiles may use resolveParsedSensorSpectralResponseAtWavelength
-to avoid repeating full profile parsing for every wavelength node.
+The profiles are parsed here, once. Internal code that has already parsed
+both profiles can call resolveParsedSensorSpectralResponseAtWavelength, to
+avoid parsing them again for every wavelength node.
 
 ```ts
 export function resolveSensorSpectralResponseAtWavelength(
@@ -139,6 +139,17 @@ export interface ResolveSensorSpectralResponseAtWavelengthInput {
 }
 ```
 
+## SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT
+
+Current channel-binding format. v2 (package 2.0.0) serializes the parsed channel with sorted keys.
+v1 (package 1.5.0 and earlier) used the unparsed channel's JSON in insertion order; it is rejected
+with an explicit version error instead of being compared.
+
+```ts
+SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT =
+  "photivra-spectral-channel-response-canonical-json-v2" as const
+```
+
 ## SensorSpectralChannelResponse
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -195,18 +206,19 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface SensorSpectralResponseChannelBinding {
   format:
-    "photivra-spectral-channel-response-canonical-json-v1";
+    typeof SENSOR_SPECTRAL_RESPONSE_CHANNEL_BINDING_FORMAT;
   canonicalJson: string;
 }
 ```
 
 ## SensorSpectralResponseProfile
 
-Versioned channel-response data linked to one exact color-sampling profile.
-Each channel declares effective EQE, effective A/W response or separable filter
-and detector EQE, sampled support/interpolation and an explicit wavelength basis.
-Reference conditions, evidence and uncertainty retain their own validity. Names
-such as red/green/blue never supply missing curves or justify extrapolation.
+Versioned response data for the channels of one exact colour-sampling profile.
+Each channel declares an effective EQE, an effective A/W response, or separate
+filter and detector EQE curves, with its sampled range, interpolation and an
+explicit wavelength basis (air or vacuum). Reference conditions, evidence and
+uncertainty each keep their own validity. Names such as red, green or blue
+never fill in a missing curve or justify extrapolation.
 
 ```ts
 export interface SensorSpectralResponseProfile {

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

@@ -1,12 +1,12 @@
 # sensor/temporal-photo-signal.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.
 
 ## createSensorEqeTemporalPhotoSignal
 
-Re-evaluate physical input at every time before committing an owned compact
-photo signal. Detailed child evidence/uncertainty stays in the returned
-exposure diagnostics. This does not establish renderer/source execution.
+Re-evaluates the physical input at every time, then commits a compact photo
+signal. Detailed per-step evidence and uncertainty stay in the returned
+exposure diagnostics. This does not show that a renderer or source actually ran.
 
 ```ts
 export function createSensorEqeTemporalPhotoSignal(input: {
@@ -19,7 +19,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSensorEqeTemporalPhotoSignal
 
-Recompute exact midpoint count sums; declarations do not prove source truth.
+Parses a time-resolved photo signal and recomputes its midpoint sums exactly. Declarations do not prove the source is correct.
 
 ```ts
 export function parseSensorEqeTemporalPhotoSignal(value: unknown): SensorEqeTemporalPhotoSignal;
@@ -37,7 +37,7 @@ export type SensorEqePhotoExposure = SensorEqeExposureIntegration | SensorEqeTem
 
 ## SensorEqeTemporalPhotoSignal
 
-Compact untreated photo expectation; temporal identity is not stationarity evidence.
+Compact expected photo signal, before any processing. Being tied to a time window is not evidence that the light was constant.
 
 ```ts
 export interface SensorEqeTemporalPhotoSignal extends Omit<SensorEqeExposureIntegration,

package/docs/api/simulation-poc-simulation.md

@@ -1,13 +1,13 @@
 # simulation/poc-simulation.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.
 
 ## POC_SIMULATION_API_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-POC_SIMULATION_API_VERSION = "0.20.0" as const
+POC_SIMULATION_API_VERSION = "1.0.0" as const
 ```
 
 ## PocSimulationRequest
@@ -41,16 +41,16 @@ export interface PocSimulationRequest {
   };
   crop: {
     /**
-     * Legacy centered same-aspect crop factor.
+     * Legacy centred crop factor that keeps the aspect ratio.
      *
-     * When capture geometry is supplied this must remain 1. New callers should
-     * use capture.activeCaptureRect/outputCropRect instead of stacking two
-     * independent crop models.
+     * When capture geometry is supplied this must stay 1. New callers should
+     * use capture.activeCaptureRect and outputCropRect instead, rather than
+     * stacking two separate crop models.
      */
     factor: number;
   };
   /**
-   * Opt-in staged capture geometry. Omit for exact legacy POC behavior.
+   * Optional staged capture geometry. Leave it out to get the exact legacy POC behaviour.
    */
   capture?: {
     orientation: CaptureOrientation;
@@ -128,11 +128,11 @@ export interface PocSimulationResponse {
     diagonalDegrees: number;
   };
   sensor: {
-    /** Physical imaging-area/native-raster metrics from the shared sensor foundation. */
+    /** Physical imaging area and native pixel grid, from the shared sensor geometry model. */
     geometry: SensorGeometryMetrics;
     /**
-     * Backwards-compatible representative pitch used by the current composed
-     * POC calculations. This remains the horizontal pitch.
+     * The single pixel pitch the POC calculations use, kept for backwards
+     * compatibility. It is the horizontal pitch.
      */
     pixelPitchMicrometers: number;
     pitchXMicrometers: number;
@@ -151,8 +151,8 @@ export interface PocSimulationResponse {
       basis: "diagonal";
     };
     /**
-     * Axis-aware pixel-domain mapping from oriented active-capture samples to
-     * the declared output raster. Subject framing is a later crop, not another
+     * Per-axis pixel mapping from the oriented active capture area to the
+     * declared output image. Subject framing is a later crop, not another
      * resampling step.
      */
     outputSamplingScale: {
@@ -161,8 +161,9 @@ export interface PocSimulationResponse {
       axisRelativeDifference: number;
     };
     /**
-     * Additional post-output subject framing. This does not mutate physical
-     * sensor identity, active capture, or active-capture focal equivalence.
+     * Extra subject-framing crop applied after output. It does not change the
+     * physical sensor, the active capture area or the active capture's
+     * equivalent focal length.
      */
     subjectFraming?: CaptureSubjectFraming;
     motion: {
@@ -352,8 +353,8 @@ export interface PocSimulationResponse {
 
 ## simulatePocCamera
 
-Composes the validated POC calculations into a single renderer/agent-facing
-response without introducing any new photographic model.
+Runs the validated POC calculations and returns them as one response for a
+renderer or agent. It adds no new photographic model.
 
 ```ts
 export function simulatePocCamera(

package/docs/api/stabilization-camera-shake.md

@@ -1,14 +1,19 @@
 # stabilization/camera-shake.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.
 
 ## CameraShakeBlurSample
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+How far a still world point on the optical axis moves in the image during
+the exposure, in image-plane axes (+X right, +Y up). For a single axis it
+equals the deltaMm from calculateCameraRotationImageMapping() at the
+optical axis.
 
 ```ts
 export interface CameraShakeBlurSample {
+  /** +X-right image displacement in millimetres: +d·tan(yaw·t). */
   deltaXmm: number;
+  /** +Y-up image displacement in millimetres: -d·tan(pitch·t). */
   deltaYmm: number;
   distanceMm: number;
   distancePixels?: number;
@@ -32,16 +37,21 @@ export interface CameraShakeEstimate {
 
 ## estimateCameraShakeBlur
 
-Estimates sensor-plane blur from a controlled constant-angular-velocity
-handheld shake profile, with optional equivalent stabilization attenuation.
+Estimates blur on the sensor from a simple handheld-shake profile, where
+the camera turns at a constant angular velocity. An optional stabilization
+rating reduces that motion.
+
+With focusDistanceM, angular motion is projected using the ideal thin-lens
+sensor distance, like the other focus-aware projection functions. Without
+it, the nominal focal length is used, which keeps the older approximation.
 
-With focusDistanceM supplied, angular motion is projected using the same
-ideal thin-lens sensor-plane distance as the other focus-aware projection
-primitives; otherwise nominal focal length preserves the prior approximation.
+The optical projection is physically calculated. But turning a
+stabilization rating in stops into residual angular motion by 2^-stops is
+an educational approximation. It is not a CIPA DC-011 measurement or a
+real-camera rating.
 
-The optical projection is physically calculated, but mapping a stabilization
-rating in stops to residual angular motion by 2^-stops is an educational
-approximation. It is not a CIPA DC-011 measurement or a real-camera rating.
+Each axis's rotation during the exposure must stay below a quarter turn
+(π/2 rad).
 
 ```ts
 export function estimateCameraShakeBlur(
@@ -59,6 +69,15 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface EstimateCameraShakeBlurInput {
   focalLengthMm: number;
   shutterSeconds: number;
+  /**
+   * Constant camera angular velocity in radians per second. Signs follow the
+   * same physical right-hand rule as calculateCameraRotationImageMapping().
+   * The camera axes are +X right, +Y up, +Z forward (a left-handed basis).
+   * - Positive yaw turns the optical axis left and moves still image content
+   *   toward +X.
+   * - Positive pitch tilts the optical axis up and moves still image content
+   *   toward -Y.
+   */
   angularVelocityRadPerSec: {
     yaw: number;
     pitch: number;

package/docs/api/stabilization-system.md

@@ -1,15 +1,16 @@
 # stabilization/system.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.
 
 ## calculateStabilizedCaptureTemporalSamples
 
-Feed the residual stabilized rotation into the existing local-exposure temporal mapping without
-changing shutter timing or inventing a blur radius.
+Feeds the residual stabilized rotation into the existing local-exposure temporal mapping. Shutter
+timing is not changed, and no blur radius is invented.
 
-Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
-and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
-calibration, arbitrary stop rating or inferred coordination is supplied.
+The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
 
 ```ts
 export function calculateStabilizedCaptureTemporalSamples(
@@ -42,12 +43,13 @@ export interface CalculateStabilizedCaptureTemporalSamplesInput {
 
 ## calculateStabilizedRotationTrajectory
 
-Evaluate the declared generic per-axis controller against an explicit angular disturbance trajectory
-and return residual motion with latency/limit diagnostics.
+Runs the declared generic per-axis controller against an explicit angular disturbance trajectory.
+Returns the residual motion, with diagnostics for latency and travel limits.
 
-Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
-and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
-calibration, arbitrary stop rating or inferred coordination is supplied.
+The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
 
 ```ts
 export function calculateStabilizedRotationTrajectory(
@@ -75,12 +77,13 @@ export interface CalculateStabilizedRotationTrajectoryInput {
 
 ## parseStabilizationDisturbanceTrajectory
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
-and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
-calibration, arbitrary stop rating or inferred coordination is supplied.
+The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
 
 ```ts
 export function parseStabilizationDisturbanceTrajectory(
@@ -92,12 +95,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseStabilizationSystemProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
-and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
-calibration, arbitrary stop rating or inferred coordination is supplied.
+The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
 
 ```ts
 export function parseStabilizationSystemProfile(