@photivra/engine 1.5.0 → 2.1.0

package/docs/api/gpu-image-kernel-execution.md

@@ -0,0 +1,152 @@
+# gpu/image-kernel-execution.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## composeRelativeErrorBounds
+
+Composes two `relative-to-reference` bounds through a pipeline `second ∘ first`, where the second
+stage is linear with non-negative weights summing to at most `secondWeightSum` per output (convolution,
+temporal sums). With |ã − a| ≤ r₁a + a₁ elementwise and |B̃x − Bx| ≤ r₂Bx + a₂:
+|B̃ã − Ba| ≤ |B̃ã − Bã| + |B(ã − a)| ≤ r₂(1 + r₁)Ba + r₂W·a₁ + a₂ + r₁Ba + W·a₁,
+so r = r₁ + r₂ + r₁r₂ and a = a₂ + W·a₁·(1 + r₂). See docs/WEBGPU.md, "Accuracy contract".
+
+```ts
+export function composeRelativeErrorBounds(first: ImageKernelRelativeErrorBound, second: ImageKernelRelativeErrorBound,
+  secondWeightSum: number): ImageKernelRelativeErrorBound;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ImageKernelBackend
+
+Requested or actual execution backend.
+
+```ts
+export type ImageKernelBackend = "cpu-reference" | "webgpu-f32";
+```
+
+## ImageKernelCodeErrorBound
+
+Integer output codes: |code_webgpu − code_reference| ≤ maximumAbsoluteCodeDifference for every sample.
+
+```ts
+export interface ImageKernelCodeErrorBound {
+  kind: "integer-code-difference";
+  maximumAbsoluteCodeDifference: number;
+  /** Bound on the float32 linear value entering the sRGB transfer, after tone and gamut handling. */
+  linearAbsoluteBound: number;
+  /** Declared bound on the WGSL sRGB transfer evaluation (pow), see WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND. */
+  transferAbsoluteBound: number;
+}
+```
+
+## ImageKernelExecution
+
+Label attached to every accelerated result.
+
+```ts
+export interface ImageKernelExecution {
+  backend: ImageKernelBackend;
+  requestedBackend: ImageKernelBackend;
+  fallbackReason: ImageKernelFallbackReason | null;
+  arithmetic: "float64" | "float32";
+  assurance: "engine-reference" | "approximation-with-a-priori-bound";
+  /**
+   * True only for `cpu-reference`. Bit-exact identities (SHA-256 artifact bindings, byte-parity fixtures,
+   * cross-engine determinism hashes) are CPU-only and must never be computed from a `webgpu-f32` result.
+   */
+  bitIdenticalToReference: boolean;
+  errorBound: ImageKernelCodeErrorBound | ImageKernelRelativeErrorBound | ImageKernelSeededRealizationBound | null;
+  /**
+   * Diagnostic counts equal the reference when no sample fell inside a float32 classification band
+   * (`diagnosticUncertaintySampleCount === 0`). Otherwise each count differs by at most that many
+   * samples.
+   */
+  diagnosticsExact: boolean;
+  diagnosticUncertaintySampleCount: number;
+  limitations: readonly string[];
+}
+```
+
+## ImageKernelExecutionError
+
+Domain error for getting and running a backend. Input validation still throws the engine's existing errors.
+
+```ts
+export class ImageKernelExecutionError extends Error {
+  readonly code = "IMAGE_KERNEL_EXECUTION";
+  readonly reason: ImageKernelFailureReason;
+
+  constructor(reason: ImageKernelFailureReason, message: string) {
+    super(message);
+    this.name = "ImageKernelExecutionError";
+    this.reason = reason;
+  }
+}
+```
+
+## ImageKernelFailureReason
+
+Failure classes reported by {@link ImageKernelExecutionError}.
+
+```ts
+export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification";
+```
+
+## ImageKernelFallbackReason
+
+Why a requested WebGPU backend was not used (only with `fallback: "cpu-reference"`).
+
+```ts
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "adapter-unavailable" | "device-request-failed" |
+  "insufficient-limits" | "unsupported-platform-endianness";
+```
+
+## ImageKernelRelativeErrorBound
+
+Non-negative linear sums: |v_webgpu − v_reference| ≤ relative·v_reference + absolute for every sample.
+
+```ts
+export interface ImageKernelRelativeErrorBound {
+  kind: "relative-to-reference";
+  relative: number;
+  absolute: number;
+}
+```
+
+## ImageKernelSeededRealizationBound
+
+Seeded stochastic stages (the sensor stage). Random states are integer arithmetic and bit-identical to
+the reference. A site is flagged when any float32 decision (sampling test, saturation limit, rounding)
+fell inside its a-priori bound. Every unflagged site has exactly the reference code and flags; only
+flagged sites may differ, and the statistical-equivalence tests cover them (docs/WEBGPU.md).
+
+```ts
+export interface ImageKernelSeededRealizationBound {
+  kind: "exact-except-flagged-sites";
+  /** Number of flagged sites; equal to the execution's `diagnosticUncertaintySampleCount`. */
+  flaggedSiteCount: number;
+  noiseModel: { id: string; version: string };
+  seedSchedule: string;
+}
+```
+
+## WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND
+
+Declared absolute error bound for the WGSL sRGB encode on [0, 1]: `1.055·pow(x, 1/2.4) − 0.055`. pow
+takes its accuracy from exp2(y·log2 x) (log2: 3 ULP, or 2^-21 absolute on [0.5, 2]; exp2: 3 + 2|x|
+ULP). The worst case over [0.0031308, 1] is about 2.5e-6. The bound 2^-17 ≈ 7.6e-6 keeps a 3× margin,
+and also covers the small jump where the sRGB segments join (< 1e-7).
+
+```ts
+WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND = 2 ** -17
+```
+
+## WEBGPU_F32_UNIT_ROUNDOFF
+
+IEEE 754 binary32 unit roundoff.
+
+```ts
+WEBGPU_F32_UNIT_ROUNDOFF = 2 ** -24
+```

package/docs/api/motion-camera-rotation.md

@@ -1,6 +1,6 @@
 # motion/camera-rotation.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.
 
 ## AxisSamplingPitchMicrometers
 
@@ -18,14 +18,14 @@ export interface AxisSamplingPitchMicrometers {
 Maps one stationary-world ray to its image-plane location after pure camera
 rotation at an arbitrary physical time from exposure start.
 
-The initial image point defines the world ray in the camera frame at t=0.
-Constant angular velocity is integrated as one axis-angle rotation vector,
-avoiding Euler-order dependence. The stationary world ray is then expressed
-in the rotated camera frame using the inverse camera rotation and projected
-rectilinearly back onto the image plane.
+The starting image point defines the world ray in the camera frame at t=0.
+Constant angular velocity is integrated as a single axis-angle rotation
+vector, which avoids any dependence on Euler-angle order. The world ray is
+then expressed in the rotated camera frame with the inverse camera rotation,
+and projected rectilinearly back onto the image plane.
 
-This function models rotation only. It deliberately excludes camera
-translation because translational optical flow depends on scene depth.
+Only rotation is modelled. Camera translation is deliberately left out,
+because the image motion it causes depends on scene depth.
 
 ```ts
 export function calculateCameraRotationImageMapping(
@@ -46,7 +46,7 @@ export interface CalculateCameraRotationImageMappingInput {
   /**
    * Stationary-world-ray image-plane position at exposure start.
    *
-   * Image-plane coordinates use optical-axis origin, +X right, +Y up.
+   * Image-plane coordinates have their origin on the optical axis, +X right, +Y up.
    */
   imagePointMm: ImagePlanePointMm;
   /**
@@ -56,16 +56,20 @@ export interface CalculateCameraRotationImageMappingInput {
   /**
    * Constant camera angular-velocity vector in radians per second.
    *
-   * Components are resolved in the camera axes at exposure start and follow
-   * the right-hand rule: pitch about +X, yaw about +Y, roll about +Z.
+   * Components are given in the camera axes at exposure start and follow the
+   * physical right-hand rule:
+   * - pitch about +X: positive tilts up; content moves toward image -Y;
+   * - yaw about +Y: positive turns left; content moves toward image +X;
+   * - roll about +Z: positive is clockwise seen from behind the camera.
+   * See CameraAngularVelocityRadPerSec.
    */
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /** Optional focus distance in metres for thin-lens projection distance. */
   focusDistanceM?: number;
   /**
-   * Optional axis-aware geometric sampling pitch for reporting sample-domain
-   * displacement. This is geometric sample spacing, not photosite collection
-   * area.
+   * Optional sampling pitch per axis, used to also report the displacement in
+   * samples. This is the geometric spacing of samples, not the light-collecting
+   * area of a photosite.
    */
   samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
 }
@@ -76,9 +80,9 @@ export interface CalculateCameraRotationImageMappingInput {
 Maps a captured stationary-world ray at one non-negative capture time back
 to its image-plane location at exposure start.
 
-For the existing constant-axis pure-rotation model this inverse is analytic:
-the captured ray is transformed by the forward camera rotation before
-rectilinear projection. No iterative solver is required.
+For this constant-axis, pure-rotation model the inverse is analytic: apply
+the forward camera rotation to the captured ray, then project
+rectilinearly. No iterative solver is needed.
 
 ```ts
 export function calculateInverseCameraRotationImageMapping(
@@ -98,7 +102,7 @@ export interface CalculateInverseCameraRotationImageMappingInput {
   focalLengthMm: number;
   /**
    * Captured image-plane location of a stationary world ray at the requested
-   * time. Coordinates use optical-axis origin, +X right and +Y up.
+   * time. Coordinates have their origin on the optical axis, +X right, +Y up.
    */
   imagePointMm: ImagePlanePointMm;
   /**
@@ -114,8 +118,8 @@ export interface CalculateInverseCameraRotationImageMappingInput {
   /** Optional focus distance in metres for thin-lens projection distance. */
   focusDistanceM?: number;
   /**
-   * Optional axis-aware geometric sampling pitch for reporting sample-domain
-   * inverse displacement.
+   * Optional sampling pitch per axis, used to also report the inverse
+   * displacement in samples.
    */
   samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
 }
@@ -123,15 +127,28 @@ export interface CalculateInverseCameraRotationImageMappingInput {
 
 ## CameraAngularVelocityRadPerSec
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+Camera angular velocity in radians per second about the exposure-start
+camera axes (+X right, +Y up, +Z forward along the optical axis).
+
+Signs follow the physical right-hand rule about each named axis. These axes
+form a left-handed basis. So a positive rotation is the mirror image of what
+the plain component Rodrigues (cross-product) formula would give in it:
+
+- Positive pitch tilts the optical axis up. Still scene content moves
+  toward image -Y (down).
+- Positive yaw turns the optical axis left (counter-clockwise seen from
+  above). Still scene content moves toward image +X (right).
+- Positive roll turns the camera clockwise, as seen by the photographer
+  looking along +Z. Still scene content rotates counter-clockwise in the
+  +X-right/+Y-up image plane.
 
 ```ts
 export interface CameraAngularVelocityRadPerSec {
-  /** Right-hand rotation rate about camera +X (right), in radians per second. */
+  /** Right-hand rotation rate about camera +X (right): positive tilts the optical axis up. */
   pitch: number;
-  /** Right-hand rotation rate about camera +Y (up), in radians per second. */
+  /** Right-hand rotation rate about camera +Y (up): positive turns the optical axis left. */
   yaw: number;
-  /** Right-hand rotation rate about camera +Z (forward), in radians per second. */
+  /** Right-hand rotation rate about camera +Z (forward): positive rolls the camera clockwise as seen from behind it. */
   roll: number;
 }
 ```
@@ -158,8 +175,8 @@ export interface CameraRotationImageMapping {
     distance: number;
   };
   /**
-   * Optional geometric sample displacement in the image-plane basis
-   * (+X right, +Y up). This is not a native-raster vector.
+   * Optional displacement in samples, in image-plane axes (+X right, +Y up).
+   * This is not a vector in native raster axes.
    */
   deltaImagePlaneSamples?: {
     x: number;

package/docs/api/motion-capture-rotation-inverse-mapping.md

@@ -1,24 +1,24 @@
 # motion/capture-rotation-inverse-mapping.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.
 
 ## calculateCaptureRotationInverseMappings
 
-Calculates an instantaneous inverse capture-scan mapping for stationary
-world rays under pure camera rotation.
+Calculates an instantaneous inverse capture-scan mapping for still world
+rays under pure camera rotation.
 
-The destination native sensor location is authoritative for local exposure
-timing. At an explicit phase within that local window, the captured
-image-plane ray is analytically mapped back to the reference image plane at
-the first opening-boundary phase.
+The destination point on the native sensor sets the local exposure timing.
+At a chosen phase within that local window, the captured image-plane ray is
+mapped back analytically to the reference image plane at the first
+opening-boundary phase.
 
-No fixed-point/iterative solve is used because pure rotation under the
-existing constant-axis model has an analytic inverse once destination
-location and local capture time are known.
+No iterative solve is needed. Once the destination and local capture time
+are known, pure rotation under this constant-axis model has an analytic
+inverse.
 
-This function is not a finite-exposure renderer and does not integrate blur.
-Sensor data-readout timing is deliberately absent; exposure boundaries are
-the only timing source.
+This is not a renderer for a finite exposure, and it does not integrate
+blur. Sensor data-readout timing is deliberately not used; exposure
+boundaries are the only timing source.
 
 ```ts
 export function calculateCaptureRotationInverseMappings(
@@ -40,17 +40,18 @@ export interface CalculateCaptureRotationInverseMappingsInput
   focusDistanceM?: number;
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /**
-   * Fraction of each point's local exposure interval at which the
-   * instantaneous mapping is evaluated.
+   * Where in each point's local exposure interval to evaluate the
+   * instantaneous mapping, as a fraction.
    *
    * 0 = local exposure start, 0.5 = local midpoint, 1 = local exposure end.
-   * A phase is required because finite exposure has no single sharp geometry.
+   * A phase is required because a finite exposure has no single sharp
+   * geometry.
    */
   localExposurePhase: number;
   /**
-   * Physical capture orientation used only to rotate the reported native
-   * inverse sample-displacement vector into oriented-capture coordinates.
-   * It does not alter the native exposure schedule.
+   * Physical capture orientation. It is used only to rotate the reported
+   * native inverse displacement (in samples) into oriented-capture
+   * coordinates. It does not change the native exposure schedule.
    */
   orientation: CaptureOrientation;
   samplePointsNative: readonly RasterPoint[];
@@ -101,8 +102,8 @@ export interface CaptureRotationInverseMappingSample {
   localExposurePhase: number;
   captureTimeSecondsFromReference: number;
   /**
-   * Same stationary world ray expressed in the exposure-start reference image
-   * plane. This may lie outside the active capture; it is intentionally not
+   * The same still world ray on the reference image plane at exposure start.
+   * It may lie outside the active capture area; it is deliberately not
    * clamped.
    */
   referenceImagePointMm: ImagePlanePointMm;
@@ -112,8 +113,8 @@ export interface CaptureRotationInverseMappingSample {
     distance: number;
   };
   /**
-   * Reference-minus-destination displacement in continuous native effective
-   * raster-sample units (+X right, +Y down).
+   * Reference minus destination displacement, in continuous native effective
+   * raster samples (+X right, +Y down).
    */
   inverseDisplacementNativeSamples: RasterVector & {
     distance: number;

package/docs/api/motion-capture-rotation-temporal-quadrature.md

@@ -1,26 +1,26 @@
 # motion/capture-rotation-temporal-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.
 
 ## calculateCaptureRotationTemporalQuadrature
 
-Builds deterministic temporal quadrature nodes for pure-camera-rotation
-capture geometry over each destination point's local exposure interval.
+Builds deterministic time samples (temporal quadrature nodes) for a
+rotating camera, across each destination point's local exposure interval.
 
-The first model uses an equal-width midpoint rule. Every node reuses
-calculateCaptureRotationInverseMappings(), so the instantaneous geometry has
-one authoritative implementation.
+The first model uses an equal-width midpoint rule. Every node calls
+calculateCaptureRotationInverseMappings(), so the instantaneous geometry
+has a single implementation.
 
-No radiance is evaluated here. normalizedTimeWeight is suitable for a
-downstream time-average under a uniform temporal-response assumption, while
-timeMeasureSeconds is the local dt measure for a downstream time integral.
-Neither weight includes shutter transmission, scene flicker, sensor
-response, radiometric calibration or any other throughput term.
+No radiance is evaluated here. normalizedTimeWeight is for a time average,
+assuming a uniform response over time. timeMeasureSeconds is the local dt
+for a time integral. Neither weight includes shutter transmission, scene
+flicker, sensor response, radiometric calibration or any other throughput
+term.
 
-The function intentionally reports no numerical integration error estimate:
-geometry alone cannot determine the error in a scene-radiance integral.
-Downstream renderers may compare increasing temporal sample counts in their
-own radiance domain when convergence evidence is required.
+No numerical integration error estimate is reported, on purpose. Geometry
+alone cannot tell the error in a scene-radiance integral. A renderer that
+needs evidence of convergence can compare results for increasing sample
+counts in its own radiance domain.
 
 ```ts
 export function calculateCaptureRotationTemporalQuadrature(
@@ -41,8 +41,8 @@ export interface CalculateCaptureRotationTemporalQuadratureInput
     "localExposurePhase"
   > {
   /**
-   * Number of deterministic temporal quadrature nodes per local exposure
-   * interval. Nodes use the uniform midpoint rule.
+   * Number of time samples (quadrature nodes) per local exposure interval.
+   * Nodes follow the uniform midpoint rule.
    */
   temporalSampleCount: number;
 }
@@ -83,15 +83,15 @@ export interface CaptureRotationTemporalQuadratureNode {
   localExposurePhase: number;
   captureTimeSecondsFromReference: number;
   /**
-   * Dimensionless weight for approximating the time-average of a downstream
-   * quantity under a uniform temporal-response assumption.
+   * Dimensionless weight for approximating the time average of a quantity,
+   * assuming a uniform response over time.
    */
   normalizedTimeWeight: number;
   /**
-   * Seconds-valued quadrature measure for approximating a time integral.
+   * Quadrature measure in seconds, for approximating a time integral.
    *
-   * This is temporal measure only. It is not shutter transmission, radiometric
-   * throughput, photon count, sensor response, or scene radiance.
+   * This is a measure of time only. It is not shutter transmission,
+   * radiometric throughput, photon count, sensor response or scene radiance.
    */
   timeMeasureSeconds: number;
   referenceImagePointMm: ImagePlanePointMm;

package/docs/api/motion-capture-rotation-trajectory.md

@@ -1,26 +1,26 @@
 # motion/capture-rotation-trajectory.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.
 
 ## calculateCaptureRotationTrajectories
 
 Evaluates pure-camera-rotation trajectories for stationary reference rays
 over each point's local exposure window.
 
-This is a temporal-geometry bridge, not a finished rolling-shutter image
-mapping. The native sample point defines where a stationary world ray would
-land in the reference global-shutter image at the first opening-boundary
-phase. The existing camera-rotation model is then evaluated at that point's
-local exposure start and end.
+This links timing to geometry. It is not a finished rolling-shutter image
+mapping. The native sample point sets where a still world ray would land in
+the reference global-shutter image at the first opening-boundary phase. The
+existing camera-rotation model is then evaluated at that point's local
+exposure start and end.
 
-Sensor data-readout timing is intentionally absent. A camera/mode-specific
-relationship between sensor readout and exposure boundaries requires a
-separate explicit contract; this function never assumes one.
+Sensor data-readout timing is deliberately not used. How readout relates to
+exposure boundaries depends on the camera and mode, and needs its own
+explicit contract. This function never assumes one.
 
-A later renderer-facing rolling-shutter warp must solve the image mapping
-consistently with capture-location-dependent time and integrate over the
-local exposure interval. The endpoint chord returned here must not be treated
-as a blur kernel or as an inverse destination-to-source sampling map.
+A future rolling-shutter warp for renderers must solve the image mapping
+with time that depends on capture location, and must integrate over the
+local exposure interval. Do not treat the endpoint chord returned here as a
+blur kernel or as an inverse destination-to-source sampling map.
 
 ```ts
 export function calculateCaptureRotationTrajectories(
@@ -51,8 +51,8 @@ export interface CalculateCaptureRotationTrajectoriesInput
    */
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /**
-   * Native points whose stationary-reference-ray trajectories should be
-   * evaluated. Required and non-empty for this trajectory API.
+   * Native points whose still-ray paths to evaluate. Required, and must not be
+   * empty.
    */
   samplePointsNative: readonly RasterPoint[];
 }

package/docs/api/motion-capture-translation-parallax-temporal-quadrature.md

@@ -1,15 +1,16 @@
 # motion/capture-translation-parallax-temporal-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.
 
 ## calculateCaptureTranslationParallaxTemporalQuadrature
 
-Evaluates depth-dependent translational parallax at deterministic midpoint
-nodes over each scene point's authoritative local exposure window.
+Evaluates depth-dependent parallax from camera movement at deterministic
+midpoint time samples across each scene point's local exposure window.
 
-The model is deliberately per point. Camera translation and optional subject
-translation coexist through relative linear motion; neither is redefined as
-the other. Camera rotation and visibility/occlusion remain separate models.
+The model works point by point, on purpose. Camera movement and optional
+subject movement combine as relative linear motion; neither is recast as
+the other. Camera rotation, and visibility or occlusion, are separate
+models.
 
 ```ts
 export function calculateCaptureTranslationParallaxTemporalQuadrature(
@@ -35,8 +36,8 @@ export interface CalculateCaptureTranslationParallaxTemporalQuadratureInput {
   orientation:
     CaptureOrientation;
   /**
-   * Constant physical camera-center translation in camera axes at the capture
-   * reference phase. Rotation is intentionally separate.
+   * Constant movement of the camera centre, in camera axes at the capture
+   * reference phase. Rotation is handled separately, on purpose.
    */
   cameraTranslationVelocityMps:
     Vector3;
@@ -54,19 +55,19 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CaptureTranslationParallaxSceneSample {
   sampleId: string;
   /**
-   * Native destination point whose authoritative local exposure window applies
-   * to this scene sample.
+   * Native destination point. Its local exposure window applies to this scene
+   * sample.
    */
   destinationPointNative:
     RasterPoint;
   /**
-   * Metric point position in the camera axes at the first-opening-boundary
-   * phase. +X right, +Y up, +Z forward/away from the camera.
+   * Point position in metres, in the camera axes at the first opening-boundary
+   * phase. +X right, +Y up, +Z forward (away from the camera).
    */
   positionCameraM: Vector3;
   /**
-   * Optional constant subject/world-point velocity in the same initial camera
-   * axes. Omitted means stationary world point.
+   * Optional constant velocity of the subject (world point), in the same
+   * starting camera axes. If omitted, the world point is still.
    */
   subjectVelocityMps?: Vector3;
 }

package/docs/api/motion-extended-object-projection.md

@@ -1,11 +1,12 @@
 # motion/extended-object-projection.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.
 
 ## calculateCaptureExtendedObjectTemporalProjection
 
-Evaluates extended-object projection at deterministic midpoint nodes inside
-each point's authoritative #12 local exposure window.
+Evaluates extended-object projection at deterministic midpoint time samples
+inside each point's local exposure window (from the capture exposure
+schedule).
 
 ```ts
 export function calculateCaptureExtendedObjectTemporalProjection(
@@ -44,8 +45,9 @@ export interface CalculateCaptureExtendedObjectTemporalProjectionInput {
 Evaluates multiple explicit metric points on one rigidly translating object
 at deterministic physical times.
 
-This is geometry only. It does not synthesize a blur kernel, visibility,
-radiance integration, deformation, camera rotation or a universal scale.
+This is geometry only. It does not build a blur kernel, decide visibility,
+integrate radiance, deform the object, rotate the camera or apply a
+universal scale.
 
 ```ts
 export function calculateExtendedObjectProjectionTrajectory(
@@ -86,8 +88,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CaptureExtendedObjectMetricPoint
   extends ExtendedObjectMetricPoint {
   /**
-   * Native destination point selecting the authoritative #12 local exposure
-   * window for this object point.
+   * Native destination point. It selects the local exposure window (from the
+   * capture exposure schedule) for this object point.
    */
   destinationPointNative:
     RasterPoint;
@@ -198,7 +200,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface ExtendedObjectMetricPoint {
   pointId: string;
   /**
-   * Metric camera-space point at the common reference phase.
+   * Point in camera space, in metres, at the shared reference phase.
    *
    * +X right, +Y up, +Z forward/away from the camera.
    */

package/docs/api/motion-projected-motion.md

@@ -1,20 +1,20 @@
 # motion/projected-motion.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.
 
 ## calculateProjectedMotionBlur
 
 Calculates sensor-plane motion during an exposure using ideal rectilinear
 projection and constant linear object velocity.
 
-Without focusDistanceM, nominal focal length is the backwards-compatible
-pinhole projection distance. With focusDistanceM, the selected thin-lens
-sensor-plane image distance is used.
+Without focusDistanceM, the projection distance is the nominal focal length
+(the older pinhole behaviour). With focusDistanceM, it is the thin-lens
+image distance for that focus.
 
-The calculation projects the object's shutter-open and shutter-close
-positions onto the image plane and measures the displacement between them.
-It therefore handles lateral and depth-direction motion without relying on a
-generic "subject speed" category.
+The object's positions when the shutter opens and closes are both projected
+onto the image plane, and the distance between them is measured. So
+sideways motion and motion toward or away from the camera are both handled,
+without a generic "subject speed" category.
 
 ```ts
 export function calculateProjectedMotionBlur(