@photivra/engine 2.20.0 → 2.22.0

package/docs/api/facade-simulate-capture.md

@@ -70,10 +70,14 @@ export interface DisplayViewResult {
   sensor: SimulateCaptureSensorReport;
   /**
    * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
-   * a quarter of the samples per axis (uniform), display pixels whose value includes the AHD low-signal correction, and wall-clock
-   * milliseconds (diagnostic only; never affects the samples).
+   * a quarter of the samples per axis (uniform), and wall-clock milliseconds (diagnostic only; never affects the samples).
    */
-  diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
+  diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number;
+    /**
+     * Display pixels whose value included the AHD low-signal correction (2.10–2.21).
+     * @deprecated Since 2.22.0 the view has no such correction, and this is always 0. Removed in 3.0.0.
+     */
+    ahdCorrectedPixelCount: number;
     timingsMs: { view: number; total: number };
     /** #395: exact or fast, as requested and as run; 2.11 (#481): plus `execution`, where the render ran (see {@link DisplayViewFastReport}). */
     fast: DisplayViewFastReport;
@@ -144,7 +148,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "sensor.spectralStepNanometers", "motion.rotation", "motion.subject", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
   "output.diffractionCorrection", "output.sharpening", "output.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -175,7 +179,8 @@ the record form with `fast` and is reported in `diagnostics.fast.applied` when i
 whether or not it has a fast method yet; one without runs exact and reports `false`.
 
 ```ts
-SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd", "motion.subject",
+  "sensor.spectralStepNanometers"] as const)
 ```
 
 ## SIMULATE_CAPTURE_METERING_MODES
@@ -473,8 +478,9 @@ export interface SimulateCaptureFastReport {
 
 `lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
 Fast: the tabulated fast method (#568), and with `lens.defocus` the lens's bokeh without its cat's eye (#567; fast wides and
-normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower). Exact: the per-site PSF with the
-cat's eye. Blades and spherical aberration always apply (they cost nothing).
+normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower); with camera rotation under
+`motion.shutter: "rolling"`, the per-tap PSF points instead of the lattice reading (#588). Exact: the per-site PSF with the
+cat's eye, read on the lattice. Blades and spherical aberration always apply (they cost nothing).
 
 ```ts
 export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
@@ -529,6 +535,11 @@ export interface SimulateCaptureMotion {
   shutter?: "global" | "rolling";
   /** Rolling shutter only: time from the first to the last line over the simulated frame, in s. Default: the body's declared readout skew. */
   rollingShutterSkewSeconds?: number;
+  /**
+   * #551: a moving subject: the whole scene, or one rectangle of it over a still background, translating on the scene plane
+   * (and optionally rotating about the optical axis) during the exposure. Off by default (a still scene).
+   */
+  subject?: SimulateCaptureSubjectMotion;
 }
 ```
 
@@ -672,9 +683,10 @@ export interface SimulateCaptureOptions {
   /**
    * Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card), a declared `material-layers` scene (#491:
    * a chart under shape-mask layers, as `resolveChartMaterialLayers` takes it; the capture is that of its `callerScene`, byte for
-   * byte, and the display view can render it on the GPU), or a caller reflectance, radiance or material function.
+   * byte, and the display view can render it on the GPU), a caller reflectance, radiance or material function, or (2.21, #581) an
+   * `image-plane` scene: a photo as a flat print (docs/IMAGE_PLANE.md).
    */
-  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -689,6 +701,12 @@ export interface SimulateCaptureOptions {
   illuminant?: CaptureIlluminant;
   /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
   illuminanceLux?: number;
+  /**
+   * 2.22 (#550), opt-in mixed lighting: two or more sources blended across the chart (docs/MIXED_ILLUMINATION.md), instead of
+   * `illuminant` and `illuminanceLux`. The frame center's light sets the grey-card meter and the standard-exposure figures, and
+   * its strongest source the "scene-illuminant" white balance; both are reported in `assumptions`.
+   */
+  illumination?: MixedIllumination;
   output?: {
     /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
     width?: number;
@@ -699,8 +717,12 @@ export interface SimulateCaptureOptions {
     toneCurve?: SdrToneCurve;
     /** Required by the luminance tone curves (see `SdrToneCurveParameters`). The facade does not make one up. */
     toneCurveParameters?: SdrToneCurveParameters;
-    /** Default "clip". */
-    highlightMode?: RawHighlightMode;
+    /**
+     * Default "clip". 2.22.0 (#602, opt-in): "reconstruct-neighbors" rebuilds clipped channels from color ratios of the unclipped
+     * pixels around each clipped region (an estimate; `src/color/neighbor-highlight-reconstruction.ts`): the ring's mean ratios
+     * (fast) or their harmonic interpolation inward (full). Whole-image, so not with `output.region`.
+     */
+    highlightMode?: SimulateCaptureHighlightMode;
     /**
      * Opt-in (#556) development exposure push in stops, −2 to +5 (`NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS`); default 0.
      * A linear gain 2^stops on the RAW after black subtraction and white normalization, before demosaic, white balance,
@@ -711,6 +733,14 @@ export interface SimulateCaptureOptions {
      * honour it. Reported in the assumption `output.exposureCompensationStops`. 0 or omitted: byte-identical to before.
      */
     exposureCompensationStops?: number;
+    /**
+     * #601 (2.22.0, opt-in): the sRGB rendering's gamut handling after the tone curve. "clip-components" (the default) clips
+     * each component to [0, 1]; "desaturate-to-luminance" moves a pixel whose largest component exceeds 1 toward the gray of its
+     * own luminance until that component is 1, keeping its luminance and hue (`desaturateToLuminance`, src/output/sdr-rendering.ts),
+     * instead of shifting bright saturated colors toward the secondaries. sRGB output only (not with a wide-gamut `colorEncoding`
+     * or `gamutMapping`). Reported in the assumption `output.gamutHandling`. Omitted: byte-identical to before.
+     */
+    gamutHandling?: SdrRenderingProfile["gamutHandling"] & ("clip-components" | "desaturate-to-luminance");
     /** Default "scene-illuminant". */
     whiteBalance?: SimulateCaptureWhiteBalance;
     /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 1 (2.20.0; 2 before), the full-quality export. */
@@ -788,6 +818,13 @@ export interface SimulateCaptureOptions {
   motion?: SimulateCaptureMotion;
   /** #555: plus the sensor characteristics ({@link SimulateCaptureSensorCharacteristics}), each off by default. */
   sensor?: SimulateCaptureSensorCharacteristics & {
+    /**
+     * #554: a sensor profile record (`SENSOR_PROFILES`, or `resolveSensorProfile(id)`), checked strictly. It replaces the body's ISO range, readout regimes
+     * (full well, read noise of each conversion gain, the dual-gain switch, high-gain storage, ADC bit depth), readout time and
+     * fixed-pattern noise, and sets the default pixel pitch and peak QE; explicit fields here still override it one at a time.
+     * Default: none (the body's own sensor). See docs/SENSOR_PROFILES.md.
+     */
+    profile?: SensorProfile;
     /**
      * Pixel pitch in micrometres, 0.5–1000. Default 6. The simulated sensor is output width × pitch wide. 2.5: above 100 µm the
      * capture is a downsized view of a whole frame (for example 36 mm / 48 pixels = 750 µm), recorded in the assumption

package/docs/api/facade-simulate-display-view.md

@@ -12,8 +12,7 @@ setup: use it to render one view in many regions, for example on each worker of
 ```ts
 export interface PreparedDisplayView {
   /**
-   * Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup and the
-   * realm's AHD correction states, which never change a byte (docs/DISPLAY_VIEW.md, "AHD at low signal"). With `gpu: "auto"`
+   * Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. With `gpu: "auto"`
    * or `"require"` (#481) GPU renders of one prepared view run one at a time on its device, and `diagnostics.fast.execution`
    * says whether the GPU or the CPU reference rendered the view, and why.
    */
@@ -25,22 +24,21 @@ export interface PreparedDisplayView {
    */
   dispose(): void;
   /**
-   * 2.10 (#447): the key of this request's AHD low-signal correction states, or null when the request has no AHD
-   * (`output.demosaic` other than "ahd"). Every input of the key is fixed when the request is prepared; two prepared views
-   * with the same key read the same states.
+   * 2.10 (#447), deprecated in 2.22.0: was the key of this request's AHD low-signal correction states. The view has no such
+   * states since 2.22.0 (docs/DISPLAY_VIEW.md, "AHD at low signal"), so this returns null for every request.
+   * @deprecated Since 2.22.0: always null. Removed in 3.0.0.
    */
   correctionKey(): string | null;
   /**
-   * 2.10 (#447): the grid keys of every correction state a render of `view` reads (ascending, whether or not this realm holds
-   * them), found by a render of the view's region that records the states instead of computing them. No image is returned;
-   * it costs about one render whose states are all held. Fails with an InvalidConfigurationError when the request has no AHD.
+   * 2.10 (#447), deprecated in 2.22.0: was the grid keys of the correction states a render of `view` read. Since 2.22.0 it checks
+   * `view` as `render` does and returns `{ key: "", gridKeys }` with no grid keys, for every request; it renders nothing.
+   * @deprecated Since 2.22.0: returns no grid keys. Removed in 3.0.0.
    */
   collectCorrectionStates(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateKeys>;
   /**
-   * 2.10 (#447): computes the correction states of `gridKeys` (from `collectCorrectionStates`, or a share of them) as a render
-   * would, stores them in this realm's cache and returns their values, for {@link bindDisplayViewCorrectionStates} in
-   * another realm. States this realm holds are read, not computed. Yields and honours `signal` like `render`. Fails with an
-   * InvalidConfigurationError when the request has no AHD or a grid key is out of range.
+   * 2.10 (#447), deprecated in 2.22.0: computed correction states. Since 2.22.0 it checks that `gridKeys` is an Int32Array of
+   * grid keys (integers in [0, 97³)) and returns `{ key: "", gridKeys, values }` with no states, for every request; it computes nothing.
+   * @deprecated Since 2.22.0: returns no states. Removed in 3.0.0.
    */
   computeCorrectionStates(gridKeys: Int32Array, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateSet>;
 }

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

@@ -139,42 +139,6 @@ export interface ImageKernelExecution {
 }
 ```
 
-## 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}. `conformance-failed` (#481): a device failed the display view's
-run-time self-check with `gpu: "require"`.
-
-```ts
-export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
-  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification" | "conformance-failed";
-```
-
-## ImageKernelFallbackReason
-
-Why a requested `webgpu-f32` backend ran the CPU reference instead. `webgpu-disabled`: `setWebGpuEnabled(false)` in this realm.
-
-```ts
-export type ImageKernelFallbackReason = "webgpu-unavailable" | "webgpu-disabled" | "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.

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

@@ -0,0 +1,23 @@
+# motion/subject-motion.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.
+
+## SimulateCaptureSubjectMotion
+
+`motion.subject` of `simulateCapture`: a moving subject on the scene plane (#551).
+
+```ts
+export interface SimulateCaptureSubjectMotion {
+  /** Velocity on the scene plane, m/s: +x right, +y up as seen from the camera. Missing components are 0. */
+  velocityMPerSec?: { x?: number; y?: number };
+  /** Rotation about the optical axis direction, rad/s, counter-clockwise as seen from the camera (+x toward +y). Default 0. */
+  angularVelocityRadPerSec?: number;
+  /**
+   * The moving part: a rectangle on the scene plane at rest (at the first opening reference), its centre and size in metres
+   * (+x right, +y up from the optical axis). Omitted: the whole scene moves.
+   */
+  region?: { centerXM: number; centerYM: number; widthM: number; heightM: number };
+  /** Exact or fast (2.20.0 convention): fast takes fewer temporal midpoints when the subject's streak is short (see the docs). */
+  fast?: boolean;
+}
+```

package/docs/api/optics-generic-lens-lateral-color.md

@@ -0,0 +1,79 @@
+# optics/generic-lens-lateral-color.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.
+
+## calculateLateralColorFringe
+
+The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the
+lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the
+given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.
+
+```ts
+export function calculateLateralColorFringe(input: CalculateLateralColorFringeInput): CalculationResult<LateralColorFringe>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLateralColorFringeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLateralColorFringeInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`). */
+  lensId: string;
+  /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** The sensor's pixel pitch, µm. */
+  pixelPitchMicrometers: number;
+  /**
+   * The field position as fractions of the frame's half-width (x, +right) and half-height (y, +up) from the optical axis, each
+   * in [−1, 1]. Default `{ x: 1, y: 1 }`: the top-right corner.
+   */
+  fieldPosition?: { x: number; y: number };
+  /**
+   * 2.21.0: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light;
+   * only `red` and `blue` are read). Default: D at the single wavelengths 610 and 465 nm.
+   */
+  channelDispersion?: ChannelDispersion;
+}
+```
+
+## LateralColorDisplacement
+
+A signed displacement of the blue image from the red one: radial (positive: blue farther from the axis) and its x and y parts.
+
+```ts
+export interface LateralColorDisplacement {
+  radial: number;
+  x: number;
+  y: number;
+}
+```
+
+## LateralColorFringe
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralColorFringe {
+  lensId: string;
+  /** The image-plane point, mm from the optical axis (+x right, +y up). */
+  imagePointMm: { x: number; y: number };
+  /** Field height H: the point's distance from the axis as a fraction of the half-diagonal (1 at the corner). */
+  fieldHeight: number;
+  /** The channel wavelengths the displacement is taken at, nm; null with a given `channelDispersion`. */
+  channelWavelengthsNm: { red: number; blue: number } | null;
+  /** The red and blue dispersions D used (normalized: 0 at the d line, F minus C = 1). */
+  channelDispersion: { red: number; blue: number };
+  /** Blue-minus-red image displacement, µm. */
+  blueMinusRedMicrometers: LateralColorDisplacement;
+  /** The same in pixels of the given pitch. */
+  blueMinusRedPixels: LateralColorDisplacement;
+  /** The fringe width: |radial| displacement, µm and pixels. */
+  fringeWidthMicrometers: number;
+  fringeWidthPixels: number;
+  /** The lens's own F-to-C (486 to 656 nm) displacement at this point, L·R·H, µm. */
+  fToCMicrometers: number;
+}
+```

package/docs/api/output-camera-channel-response.md

@@ -0,0 +1,55 @@
+# output/camera-channel-response.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.
+
+## calculateCameraChannelResponse
+
+#591: the camera's channel response on its spectral grid and, with `illuminant`, each channel's effective dispersion (pass it
+as `channelDispersion` to `calculateLateralColorFringe` or `createGenericLensCorrectionProfile`). Strict input. A labelled
+approximation: the facade's synthetic colorimetric sensor, not a measured one.
+
+```ts
+export function calculateCameraChannelResponse(input: CalculateCameraChannelResponseInput = {}): CalculationResult<CameraChannelResponse>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCameraChannelResponseInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCameraChannelResponseInput {
+  /**
+   * The capture's `sensor.profile` record (a `SensorProfile`, for example `resolveSensorProfile(id)`): only its
+   * `peakQuantumEfficiency` is read, the one field that changes the channels. Omitted: a tier body (peak QE 0.5).
+   */
+  sensorProfile?: Pick<SensorProfile, "peakQuantumEfficiency">;
+  /** Peak quantum efficiency in (0, 1] (as `sensor.peakQuantumEfficiency`); wins over the profile's. */
+  peakQuantumEfficiency?: number;
+  /**
+   * The capture's `sensor.spectralStepNanometers`, 1–100. Default 5: the calculator runs at full quality, and a spiky light
+   * needs the fine grid. Pass the capture's step to reproduce a capture's channels.
+   */
+  spectralStepNanometers?: number;
+  /** A `simulateCapture` illuminant: when given, the result also carries each channel's effective dispersion under it. */
+  illuminant?: CaptureIlluminant;
+}
+```
+
+## CameraChannelResponse
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraChannelResponse {
+  /** The capture's midpoint nodes, nm, increasing. */
+  wavelengthsNm: number[];
+  /** Electrons per joule of incident light at each node, per channel: EQE_c(λ)·λ/(h·c). */
+  red: number[];
+  green: number[];
+  blue: number[];
+  /** With `illuminant`: D̄_c, as `calculateChannelEffectiveDispersion` returns for these channels; else null. */
+  channelDispersion: ChannelDispersion | null;
+}
+```

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

@@ -2,10 +2,19 @@
 
 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.
 
+## ChannelDispersion
+
+A normalized dispersion per channel (`genericLensDispersion` units: 0 at the d line, F minus C = 1).
+
+```ts
+export type ChannelDispersion = Readonly<Record<LensCorrectionChannel, number>>;
+```
+
 ## GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM
 
 Effective wavelengths of the red, green and blue channels for the lateral-colour map, nm: a generic approximation of where
-a camera's channel responses peak, not a measured camera.
+a camera's channel responses peak, not a measured camera. The default of `createGenericLensCorrectionProfile` without a
+`channelDispersion`; `simulateCapture`'s `output.lensCorrections` uses the capture's own channels instead (#589).
 
 ```ts
 GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })

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

@@ -2,13 +2,44 @@
 
 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.
 
+## calculateChannelEffectiveDispersion
+
+#589: each channel's effective dispersion for the catalogue lenses' lateral colour, D̄_c = Σ w·D(λ) / Σ w with
+w = response_c(λ)·illuminant(λ) at the nodes and D the normalised Cauchy dispersion (`genericLensDispersion`: 0 at the
+Fraunhofer d line, F minus C = 1). Under lateral colour L·r·D(λ) a neutral surface's image in channel c moves by L·r·D̄_c, so
+blue minus red is L·r·(D̄_blue − D̄_red). Pass the result as `channelDispersion` to `createGenericLensCorrectionProfile`.
+`simulateCapture`'s `output.lensCorrections` computes it from the capture's own channels and reports it in its assumption.
+An approximation: a weighted mean over a neutral surface; a colored surface weights the band differently.
+
+```ts
+export function calculateChannelEffectiveDispersion(input: CalculateChannelEffectiveDispersionInput): CalculationResult<ChannelDispersion>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChannelEffectiveDispersionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChannelEffectiveDispersionInput {
+  /** Spectral nodes, nm, strictly increasing, within 300–1100 nm. */
+  wavelengthsNm: readonly number[];
+  /** Each channel's response at the nodes (any common linear unit, ≥ 0; for example electrons per unit spectral radiance). */
+  channelResponse: { red: readonly number[]; green: readonly number[]; blue: readonly number[] };
+  /** The illuminant's relative spectral power at the nodes (≥ 0; the scale cancels). */
+  illuminant: readonly number[];
+}
+```
+
 ## createGenericLensCorrectionProfile
 
 Builds the catalogue lens's generic correction profile for one camera state: a radial distortion map (the lens's own
-r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D(λ_channel), and the
-relative-illumination gain at the state's aperture (strength 1). From profile version 1.1.0 (#584) the vignetting component
-(version 1.1.0) carries the distortion's area factor (`distortionAreaFactor`): its gain is det J(ρ_i)/E(ρ_s) at the capture's
-sensor point, so it flattens a flat-field capture. The result passes `parseGenericLensCorrectionProfile`.
+r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D̄_channel (`channelDispersion`,
+by default D at the generic channel wavelengths), and the relative-illumination gain at the state's aperture (strength 1). From
+profile version 1.1.0 (#584) the vignetting component (version 1.1.0) carries the distortion's area factor
+(`distortionAreaFactor`): its gain is det J(ρ_i)/E(ρ_s) at the capture's sensor point, so it flattens a flat-field capture. The
+result passes `parseGenericLensCorrectionProfile`.
 
 ```ts
 export function createGenericLensCorrectionProfile(input: CreateGenericLensCorrectionProfileInput): GenericLensCorrectionProfile;
@@ -28,5 +59,10 @@ export interface CreateGenericLensCorrectionProfileInput {
   activeImagingArea: { widthMm: number; heightMm: number };
   /** The exact camera state the profile applies to: its focal length must be the lens's on this sensor, its aperture in range. */
   state: OpticalProfileState;
+  /**
+   * #589: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light).
+   * Default: D at {@link GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM} (610, 540 and 465 nm), a generic approximation.
+   */
+  channelDispersion?: ChannelDispersion;
 }
 ```

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

@@ -42,14 +42,44 @@ export function parsePrintPlanInput(value: unknown): PrintPlanInput;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PrintContainLayout
+
+The layout of a `contain` fit, in millimetres. The printed image itself is the plan's `printedImageMm`.
+
+```ts
+export interface PrintContainLayout {
+  /** The paper as placed: after the quarter turn when `paperRotated`. */
+  paperMm: { width: number; height: number };
+  paperRotated: boolean;
+  /** Unprinted border on each side of the centered image; zero when the paper has the image's aspect ratio. */
+  bordersMm: { left: number; right: number; top: number; bottom: number };
+}
+```
+
 ## PrintedImageSize
 
 The flat printed image area. It excludes paper margins, borders and canvas wraps.
+With a `contain` fit it is instead the paper, or the printable area of it, that the image is fitted inside.
 
 ```ts
 export interface PrintedImageSize { width: number; height: number; unit: PrintLength["unit"] }
 ```
 
+## PrintFit
+
+How the printed image relates to `printedImage`.
+- `confirmed-native-aspect`: `printedImage` is the printed image itself and must already have the native aspect ratio,
+ within the stated relative error.
+- `contain`: `printedImage` is the paper. The image keeps the native aspect ratio and is scaled to the largest size that
+ fits inside it, centered; the rest is unprinted border. `match-image` turns the paper a quarter turn when its
+ orientation (portrait or landscape) differs from the image's; `as-given` keeps it. Layout only: nothing is cropped or resampled.
+
+```ts
+export type PrintFit =
+  | { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number }
+  | { kind: "contain"; paperOrientation: "as-given" | "match-image" };
+```
+
 ## PrintLength
 
 A physical length. Not to be confused with image pixels or printer dots.
@@ -90,6 +120,8 @@ export interface PrintPlan {
   alternatives: { maximumImageMmAtCurrentDistance: { width: number; height: number }; minimumViewingDistanceMmAtCurrentSize: number | null } | null;
   capturedDetailAssessment: "unassessed";
   deliveryAssessment: "unassessed";
+  /** Present only with a `contain` fit; null when the native raster is unknown. */
+  contain?: PrintContainLayout | null;
 }
 ```
 
@@ -103,7 +135,7 @@ export interface PrintPlanInput {
   printedImage: PrintedImageSize;
   viewingDistance: PrintLength;
   sampling: PrintSamplingCriterion;
-  fit: { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number };
+  fit: PrintFit;
   provider?: PrintProviderConstraints;
 }
 ```
@@ -156,6 +188,8 @@ export interface PrintSizeLimit {
   maximumImageMm: { width: number; height: number } | null;
   reasons: string[];
   referencePlan: PrintPlan;
+  /** Present only with a `contain` fit: the paper that holds `maximumImageMm` with the same layout (borders scale with it). */
+  maximumPaperMm?: { width: number; height: number } | null;
 }
 ```
 

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

@@ -83,7 +83,12 @@ export interface SdrRenderingProfile {
   toneCurve: SdrToneCurve;
   /** Present exactly for `extended-reinhard-luminance` ({whiteLuminance}) and `naka-rushton-luminance`. */
   toneCurveParameters?: SdrToneCurveParameters;
-  gamutHandling: "clip-components" | "reject-out-of-range";
+  /**
+   * After the tone curve: clip each component to [0, 1], reject an out-of-range pixel, or (#601, 2.22.0) desaturate a pixel whose
+   * largest component exceeds 1 toward the gray of its own luminance until that component is 1 (`desaturateToLuminance`), then
+   * clip what remains below 0.
+   */
+  gamutHandling: "clip-components" | "reject-out-of-range" | "desaturate-to-luminance";
   outputDynamicRange: "sdr";
   transferFunction: "srgb";
   bitDepth: 8 | 16;

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

@@ -2,6 +2,49 @@
 
 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.
 
+## SimulateCaptureMidGreyFigure
+
+#535: the mid-grey noise figure of {@link SimulateCaptureSensorReport.midGrey}.
+
+```ts
+export interface SimulateCaptureMidGreyFigure { reflectance: 0.18; channel: "green"; signalElectrons: number; noiseElectrons: SimulateCaptureNoiseComponents; snr: number; snrDecibels: number; clipped: boolean }
+```
+
+## SimulateCaptureNativeSensorReport
+
+#595: {@link SimulateCaptureSensorReport.native}, the figures of one native photosite.
+
+```ts
+export interface SimulateCaptureNativeSensorReport {
+  /** The native photosite pitch, µm (tiers: 6; a profile: its own). */
+  pixelPitchMicrometers: number;
+  /** N = (rendered pitch / native pitch)²: the photosites one rendered site stands for (below 1, a site smaller than a photosite). */
+  photositesPerSite: number;
+  /** Full-well capacity of one photosite, e⁻. */
+  fullWellElectrons: number;
+  /** Read noise of one photosite at the capture's ISO, RMS e⁻ (the capture's readout regime). */
+  readNoiseElectrons: number;
+  /** Engineering dynamic range of one photosite at the capture's ISO, stops (the definition of `dynamicRangeStops`). */
+  dynamicRangeStops: number;
+  /** The same per ISO setting of the body. */
+  dynamicRangeByIso: readonly { iso: number; stops: number }[];
+  /**
+   * EMVA 1288 Release 4.0 (§2.7, Eq. 26–28) at the capture's ISO: the absolute sensitivity threshold μ_e.min = √(σ_d² + σ_q² + 1/4) + 1/2
+   * (σ_d the read noise, dark current excluded; σ_q the quantization noise in e⁻), DR = μ_e.sat / μ_e.min in stops and dB, and the
+   * saturation capacity per area μ_e.sat / p² (Table 2).
+   */
+  emva1288: { absoluteSensitivityThresholdElectrons: number; dynamicRangeStops: number; dynamicRangeDecibels: number; saturationCapacityElectronsPerSquareMicrometer: number };
+  /**
+   * A convention, not part of EMVA 1288: the dynamic range of the whole frame's native photosites resampled to 8 million output
+   * pixels, each summing framePhotosites / 8e6 photosites with their read noise (EMVA 1288 R4.0 §6.4, binning):
+   * DR + ½·log₂(framePhotosites / 8e6), for the engineering and the EMVA figure. No ADC limit is applied to the sum.
+   */
+  normalized8Megapixel: { referencePixels: 8_000_000; framePhotosites: number; dynamicRangeStops: number; emva1288DynamicRangeStops: number };
+  /** The mid-grey figure for one photosite (its charge (native/rendered pitch)² of the site's), present when `midGrey` is. */
+  midGrey?: SimulateCaptureMidGreyFigure;
+}
+```
+
 ## SimulateCaptureNoiseComponents
 
 One RMS noise component of the mid-grey figure, e⁻ (input-referred).
@@ -45,7 +88,9 @@ export interface SimulateCaptureSensorCharacteristics {
    */
   fullWell?: { electrons: number; link?: "pixel-area" | "none"; referencePixelPitchMicrometers?: number };
   /**
-   * Read noise, RMS e⁻ (0–100), of the low and the high conversion gain, and the dual-gain switch: the ISO setting from
+   * Read noise, RMS e⁻ (0–100), of one physical photosite, as a sensor datasheet gives it (2.22.0: on a tier too; a rendered site that
+   * sums N photosites, above the tier's 6 µm or a profile's own pitch, takes it ×√N), of the low and the high conversion gain, and
+   * the dual-gain switch: the ISO setting from
    * which the high conversion gain is used (any ISO from 100; above the body's highest ISO, the low gain is used throughout).
    * An omitted field keeps the body's value. Needs readout regimes that declare their exposure index (the tiers do).
    */
@@ -100,6 +145,13 @@ export interface SimulateCaptureSensorReport {
    * the figure no longer describes the image. Computed only when the request resolves to exact (`fast: false`, the default for
    * DNG, JPEG and PNG exports; omitted for a fast request).
    */
-  midGrey?: { reflectance: 0.18; channel: "green"; signalElectrons: number; noiseElectrons: SimulateCaptureNoiseComponents; snr: number; snrDecibels: number; clipped: boolean };
+  midGrey?: SimulateCaptureMidGreyFigure;
+  /**
+   * #595 (2.22.0): the same figures for one of the body's native photosites, whatever pitch the capture renders (the fields above
+   * are the as-rendered site's). The native pitch is a generic tier's (or a caller preset's) declared 6 µm reference, or a sensor
+   * profile's own photosite; the request's sensor characteristics apply as they would at that pitch. Exact arithmetic under the
+   * engine's model (model figures, not measurements); see docs/QUICK_START.md, "Native-pixel dynamic range (#595)".
+   */
+  native: SimulateCaptureNativeSensorReport;
 }
 ```

package/llms.txt

@@ -7,6 +7,9 @@
 - [Agent guide](https://github.com/Photivra/photivra/blob/main/docs/AGENT_GUIDE.md): which function to call, units, reading results, errors and limits
 - [Quick start](https://github.com/Photivra/photivra/blob/main/docs/QUICK_START.md): `simulateCapture()` inputs, defaults, chart presets and output formats
 - [Color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md): the built-in color chart patches (`color-patches` preset, `{ kind: "color-patch", patchId }`), their spectra and CIELAB
+- [Image-plane scene](https://github.com/Photivra/photivra/blob/main/docs/IMAGE_PLANE.md): a photo as a flat print in front of the camera (`{ kind: "image-plane" }`), its input, placement, print reflectance lattice and accuracy
+- [Light sources](https://github.com/Photivra/photivra/blob/main/docs/LIGHT_SOURCES.md): representative fluorescent and LED spectra designed by Photivra (`createRepresentativeLightSourceIlluminant`), their CCT and color rendering
+- [Content Credentials](https://github.com/Photivra/photivra/blob/main/docs/CONTENT_CREDENTIALS.md): embed a caller-built C2PA manifest store in a JPEG, PNG or DNG export (`bindC2paManifestStore`), hash the bound bytes (`calculateC2paDataHash`), write the signed store at the same length (`setC2paManifestStore`) and find an existing store (`parseC2paManifestStore`); no keys, signature checks or network
 - [Usage guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md): worked examples for every public area
 - [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md): every root export, with a task-to-function index