@photivra/engine 2.21.0 → 2.23.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.subject", "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", "motion.subject"] 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
@@ -712,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,
@@ -724,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. */

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/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-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

@@ -9,6 +9,7 @@
 - [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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.21.0",
+  "version": "2.23.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -105,13 +105,14 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@types/node": "24.13.6",
+    "@vitest/coverage-v8": "5.0.1",
     "eslint": "10.10.0",
+    "jxl-oxide-wasm": "0.12.6",
+    "rolldown": "1.2.9",
     "typescript": "6.0.3",
     "typescript-eslint": "8.70.0",
-    "vitest": "5.0.1",
-    "@types/node": "24.13.6",
-    "@vitest/coverage-v8": "5.0.1",
-    "rolldown": "1.2.9"
+    "vitest": "5.0.1"
   },
   "keywords": [
     "photography",