@photivra/engine 2.18.0 → 2.20.0

package/docs/api/exposure-filtered-exposure-time.md

@@ -0,0 +1,105 @@
+# exposure/filtered-exposure-time.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.
+
+## calculateFilteredExposureTime
+
+Shutter time that keeps the same exposure after adding front-of-lens filters, such as a
+neutral-density (ND) filter: t / T, with T the combined transmittance of the filter profiles.
+Aperture and ISO are unchanged.
+
+Exact under the linear sensor model (exposure H = E·t); film reciprocity failure is not modelled.
+Nominal filters vary: a "10-stop" or ND1000 (OD 3.0, 9.97 stops) filter transmits roughly, not
+exactly, its rating, so the result is only as good as the profile. The envelope is an
+approximation whenever any profile's `scientificStatus` is `"approximation"`.
+
+Example: 1/125 s with `GENERIC_ND_FILTER_PROFILES[10]` (exactly 2^-10) gives 1024/125 = 8.192 s;
+on a third-stop dial, 8 s.
+
+```ts
+export function calculateFilteredExposureTime(
+  input: CalculateFilteredExposureTimeInput
+): CalculationResult<FilteredExposureTime>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFilteredExposureTimeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFilteredExposureTimeInput {
+  /** Shutter time without the filter, in seconds. */
+  shutterSeconds: number;
+  /**
+   * One front-of-lens filter profile, or several in light-path order (scene side first), as
+   * accepted by `composeFrontOfLensFilterTransmission`.
+   */
+  filter: FrontOfLensFilterProfile | readonly FrontOfLensFilterProfile[];
+  /**
+   * Optional shutter dial, in seconds (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`). When
+   * given, the result also reports the nearest dial value (nearest in stops, the shorter on a tie).
+   */
+  shutterDialSeconds?: readonly number[];
+  /** Wavelength at which the filters are resolved. Defaults to 550 nm. Neutral filters do not depend on it. */
+  wavelengthNanometers?: number;
+  /** Wavelength basis; defaults to the first filter profile's basis and must match every profile. */
+  wavelengthBasis?: Exclude<SpectralWavelengthBasis, "unspecified">;
+  /** Incident polarization, which matters only when a polarizer is in the stack. Omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
+}
+```
+
+## FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS
+
+Wavelength used when the caller gives none: 550 nm, near the photopic peak. Neutral filters do not depend on it.
+
+```ts
+FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS = 550 as const
+```
+
+## FilteredExposureDialSetting
+
+The dial value nearest the exact filtered shutter time.
+
+```ts
+export interface FilteredExposureDialSetting {
+  /** Nearest dial value in seconds. */
+  shutterSeconds: number;
+  /**
+   * log2(dial / exact filtered time): exposure of the dial setting relative to the unfiltered
+   * exposure, in stops. Positive is brighter (longer), negative darker.
+   */
+  exposureErrorStops: number;
+  /** `"maximum"` when the exact time is longer than every dial value (use bulb for the exact time), `"minimum"` when shorter than every one. */
+  clamped: false | "minimum" | "maximum";
+  /** How the dial value was chosen. */
+  quantizationPolicy: "nearest-log2-shorter-on-tie";
+}
+```
+
+## FilteredExposureTime
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FilteredExposureTime {
+  /** Shutter time without the filter, in seconds. */
+  shutterSeconds: number;
+  /** Shutter time that gives the same exposure with the filter: shutterSeconds / linearTransmissionFactor. */
+  filteredShutterSeconds: number;
+  /** Combined intensity transmittance T of the filter stack, in (0, 1]. */
+  linearTransmissionFactor: number;
+  /** Combined attenuation −log2 T, in stops. */
+  attenuationStops: number;
+  /** Shutter multiplier 1/T = 2^attenuationStops. */
+  exposureFactor: number;
+  /** Wavelength at which the filters were resolved, in nanometres. */
+  wavelengthNanometers: number;
+  /** The filter-stack transmission this result is based on, with each filter's identity and evidence. */
+  filterTransmission: ComposedFrontOfLensFilterTransmission;
+  /** Nearest shutter-dial value; present only when `shutterDialSeconds` was given. */
+  dial?: FilteredExposureDialSetting;
+}
+```

package/docs/api/facade-develop-joined-parts.md

@@ -0,0 +1,32 @@
+# facade/develop-joined-parts.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.
+
+## simulateCaptureFromParts
+
+Develops the whole frame of `options` from the packed RAW of region renders of the same request (#571), so a capture can
+render its RAW in parallel parts and still take the development steps that filter across the whole image:
+`output.diffractionCorrection` and `output.sharpening`, which a region render refuses, and `output.lensCorrections` (#570), which
+runs on the whole developed frame here exactly as in `simulateCapture(options)`. The parts are joined exactly as
+{@link serializeSimulatedCaptureDngFromParts } joins them (they must cover every native site and agree where they overlap),
+and the joined RAW is the whole render's RAW, so the result's `image` (samples and JPEG or PNG bytes), `raw` codes and
+`plan` are those of `simulateCapture(options)`, bit for bit.
+
+`options` is the whole request (no `output.region`), with the development options it should have; render the parts with
+the same request plus `output.region`, without `output.diffractionCorrection`, `output.sharpening` and `output.dng`, and with a
+fixed white balance in place of `"auto"` (none of these change the RAW codes; auto white balance is measured here over the
+joined frame). A part may keep or drop `output.lensCorrections` (a corrected region only widens its `region.nativeRect`).
+Any `output.format` serves for a part.
+
+`onProgress` reports the `white-balance` (with auto white balance), `development`, `diffraction-correction`, `sharpening` and
+`jpeg` stages, the detail stages once per output row, so a host can show "Applying sharpening to the whole image". The lens
+corrections report no stage of their own: they run between `diffraction-correction` and `sharpening`.
+No `raw` stage is reported: no RAW is rendered. What differs from the whole render's result: `diagnostics.providerEvaluationCount`
+is 0, `diagnostics.timingsMs` are this call's, `diagnostics.fast` and the `raw.*` assumptions of how the RAW was rendered are
+not repeated (they are in the parts' results), and a `parts` assumption records the join.
+
+```ts
+export async function simulateCaptureFromParts(options: SimulateCaptureOptions, parts: readonly SimulateCaptureDngPart[]): Promise<SimulateCaptureResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

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

@@ -81,13 +81,16 @@ export type DisplayViewGpuMode = "off" | "auto" | "require";
 
 ```ts
 export interface PrepareDisplayViewOptions {
-  /** See {@link DisplayViewGpuMode}. Default `"off"`. */
+  /**
+   * See {@link DisplayViewGpuMode}. 2.20.0: default `"auto"` when the request resolves to fast (`fast` omitted or true: the
+   * display view's default) and `"off"` when it is exact (`fast: false`); an explicit value wins.
+   */
   gpu?: DisplayViewGpuMode;
   /**
    * Where the device comes from, with `gpu: "auto"` or `"require"`: a WebGPU entry point (a worker's `navigator.gpu`), or an
    * `ImageKernelAccelerator` whose device the view shares (the accelerator keeps ownership; `dispose()` of the prepared view
    * leaves it alone). Without it the engine acquires a device from `globalThis.navigator.gpu` and owns it until `dispose()`.
-   * Refused with `gpu: "off"`.
+   * Refused when `gpu` is or defaults to `"off"`.
    */
   gpuDevice?: unknown;
 }

package/docs/api/facade-fast-methods.md

@@ -0,0 +1,91 @@
+# facade/fast-methods.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.
+
+## SIMULATE_CAPTURE_FAST_METHODS
+
+2.20.0: every speed-versus-accuracy choice of the capture facade and the display view (see the module comment).
+
+```ts
+SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.freeze([
+  { id: "lens.catalogue/field-grid", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture"],
+    fast: "#568: the PSF blended over a field grid and tabulated expected electrons, verified per CFA phase against the exact chain",
+    exact: "the environment PSF quadrature with the PSF resolved at each query point", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "fast.lens.catalogue" } },
+  { id: "lens.catalogue/cats-eye", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#567: with lens.defocus, the lens's bokeh without its cat's eye (the axis kernel everywhere)",
+    exact: "the cat's eye shaped at each field point (fast wides and normals)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "fast.lens.catalogue.catsEye" } },
+  { id: "lens.catalogue/view-psf-zones", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
+    fast: "#569 (H1): 64 field zones along the longer side, each with the PSF at its centre",
+    exact: "one zone per site: the PSF at each site centre", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "view.lensPsf" } },
+  { id: "lens.diffraction/rolling-shutter-taps", override: "lens.diffraction", methods: "fast-and-exact", runs: ["simulateCapture"],
+    fast: "#565: under rolling-shutter rotation, each PSF tap reads the scene at its own source point",
+    exact: "each tap reads the scene at its site-lattice point (ties on chart boundaries resolve as on the lattice)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction", assumption: "fast.lens.diffraction" } },
+  { id: "output.demosaic.ahd/view-low-signal-correction", override: "output.demosaic", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
+    fast: "(H3) 2048 draws per correction state, applied where a pixel's linear noise exceeds 0.01",
+    exact: "8192 draws per state, at the same 0.01 threshold", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(demosaicFast, fastTop)" }, report: { applied: "output.demosaic.ahd", assumption: "view.demosaic" } },
+  { id: "view.uniform-pixel-sampling", override: "fast", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
+    fast: "(H2) a quarter of the samples per axis in display pixels whose pilot finds no detail",
+    exact: "the full samples per axis in every display pixel", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "uniformSampling: fastTop" }, report: { assumption: "view.estimation" } },
+  { id: "prepareDisplayView.gpu", override: "fast", methods: "fast-and-exact", runs: ["prepareDisplayView"],
+    fast: "gpu \"auto\": WebGPU float32 where a conforming device supports the request (a bounded approximation), else the CPU reference",
+    exact: "gpu \"off\": the CPU reference; an explicit gpu wins", followsFormatDefault: true,
+    resolver: { file: VIEW, call: "parsePrepareDisplayViewOptions(prepareOptions, (options as { fast?: unknown } | null | undefined)?.fast !== false)" },
+    report: { field: "diagnostics.fast.execution" } },
+  { id: "sensor.midGrey", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#535: the mid-gray noise figure is not computed (about 0.3 ms)", exact: "result.sensor.midGrey is computed", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "fastTop ? undefined : 0" }, report: { field: "sensor.midGrey" } },
+  { id: "lens.diffraction", override: "lens.diffraction", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "", exact: "the diffraction kernels (a fast method only under rolling-shutter rotation, above)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction" } },
+  { id: "sensor.antiAliasing", override: "sensor.antiAliasing", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "", exact: "the point-splitting filter", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "fastInUse" }, report: { applied: "sensor.antiAliasing" } },
+  { id: "sensor.pixelAperture.box", override: "sensor.pixelAperture", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "", exact: "the N × N midpoint rule", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "fastInUse" }, report: { applied: "sensor.pixelAperture.box" } },
+  { id: "output.demosaic.ahd", override: "output.demosaic", methods: "exact-only", runs: ["simulateCapture"],
+    fast: "", exact: "the AHD demosaic of the capture (a fast method only in the display view's correction, above)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(demosaicFast, fastTop)" }, report: { applied: "output.demosaic.ahd" } }
+] as const satisfies readonly SimulateCaptureFastMethod[])
+```
+
+## SimulateCaptureFastMethod
+
+One speed-versus-accuracy choice of {@link SIMULATE_CAPTURE_FAST_METHODS} (2.20.0).
+
+```ts
+export interface SimulateCaptureFastMethod {
+  /** A short id: the option path and, where one option has several fast methods, the method. */
+  id: string;
+  /**
+   * The request path whose record takes the `fast` override (`allowKeys` path in simulate-capture.ts), or "fast" when only the
+   * top-level flag sets it (a choice with no option record of its own).
+   */
+  override: string;
+  /** "fast-and-exact": both methods exist; "exact-only": the record takes `fast`, but there is no fast method yet (reports false). */
+  methods: "fast-and-exact" | "exact-only";
+  /** Where it applies. */
+  runs: readonly ("simulateCapture" | "simulateDisplayView" | "prepareDisplayView")[];
+  /** The fast method and the exact one, in words (empty for exact-only). */
+  fast: string;
+  exact: string;
+  /** Always true: no choice keeps its own default (the test checks it). */
+  followsFormatDefault: true;
+  /**
+   * The resolver call in the source (`resolveFast(<record flag>, fastTop)`, or `fastTop` itself for a top-level choice), which the
+   * test finds in the named file.
+   */
+  resolver: { file: string; call: string };
+  /**
+   * How the result reports it: the `diagnostics.fast.applied` key (true where the fast method ran), an assumption id the fast
+   * method adds, or another result field. At least one; the test finds each assumption id in the source.
+   */
+  report: { applied?: string; assumption?: string; field?: string };
+}
+```

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

@@ -66,6 +66,8 @@ export interface DisplayViewResult {
     /** #516: as in the capture result. */
     isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
+  /** #555, #535: as in the capture result. */
+  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
@@ -144,7 +146,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 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",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
-  "output.diffractionCorrection", "output.sharpening", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
+  "output.diffractionCorrection", "output.sharpening", "output.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
 
 ## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
@@ -425,6 +427,12 @@ One part of a whole-frame DNG (#391): a region render's packed RAW and where its
 export interface SimulateCaptureDngPart {
   raw: Pick<NativeRawOutput, "codes" | "blackLevels" | "digitalSaturationCodes" | "saturationFlags" | "effectiveSaturationCodes">;
   region: { nativeRect: { x: number; y: number; width: number; height: number } };
+  /**
+   * 2.20.0: true when a fast method ran for this part (`Object.values(result.diagnostics.fast.applied).includes(true)`). The join
+   * refuses such a part unless its own request resolves to fast too (a DNG, JPEG or PNG is exact by default): render the parts with
+   * the same `fast` as the join, or with `fast: false`.
+   */
+  fast?: boolean;
 }
 ```
 
@@ -450,8 +458,10 @@ export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[num
 
 ```ts
 export interface SimulateCaptureFastReport {
-  /** True when `fast: true` was given at the top level or in any option's record. */
+  /** 2.20.0: the resolved top-level value (`fast`, else the format default), or true when any option's record sets `fast: true`. */
   requested: boolean;
+  /** 2.20.0: where the top-level value came from: the request's `fast`, or the format default (see {@link SimulateCaptureOptions.fast}). */
+  defaultedFrom: "request" | "format";
   /** Each fast-capable option that ran, in {@link SIMULATE_CAPTURE_FAST_OPTIONS} order: true where its fast method ran. */
   applied: Readonly<Partial<Record<SimulateCaptureFastOption, boolean>>>;
   /** `engine-reference` when every option ran exact; `approximation-with-a-priori-bound` when any fast method ran (the WebGPU execution record's values). */
@@ -462,11 +472,30 @@ export interface SimulateCaptureFastReport {
 ## SimulateCaptureLensCatalogueRecord
 
 `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).
 
 ```ts
 export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
 ```
 
+## SimulateCaptureLensCorrections
+
+`output.lensCorrections` (#570): which of the catalogue lens's generic corrections (`createGenericLensCorrectionProfile`) the
+development applies. Each is off unless set to true.
+
+```ts
+export interface SimulateCaptureLensCorrections {
+  /** Radial distortion r_d = r(1 + k1ρ²), inverted by resampling: it stretches the corners and lowers their resolution. */
+  distortion?: boolean;
+  /** Lateral colour: each channel rescaled by 1/(1 + L·D(λ_c)) into register; axial (longitudinal) colour stays. */
+  lateralColor?: boolean;
+  /** Vignetting: a gain 1/E(ρ) at each pixel's source point; corner noise rises with the signal, the SNR does not. */
+  vignetting?: boolean;
+}
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -531,7 +560,8 @@ export interface SimulateCaptureOptions {
      * distance beyond the focal length (no minimum focus distance; `subjectDistanceM` must be at least twice the focal length, as for
      * every lens). Works in `simulateCapture` and the display view. Not combinable with `prime`, `catalogue` or `focalLengthMm`.
      * Optional `widestFNumber` and `narrowestFNumber` (within `IDEAL_LENS_LIMITS`, widest ≤ narrowest; each defaults to its bound)
-     * narrow the range: `fNumber` must lie in it, and shutter priority and program choose apertures only in it. Default off.
+     * narrow the range: `fNumber` must lie in it, and shutter priority and program choose apertures only in it (program limits its
+     * line to a range that does not hold f/4–f/16, #583). Default off.
      */
     ideal?: { focalLengthMm: number; widestFNumber?: number; narrowestFNumber?: number };
     /**
@@ -540,9 +570,9 @@ export interface SimulateCaptureOptions {
      * factor and it replaces the tier lens's focal length and f-number range (the transmission is kept). The capture renders the
      * lens's character, all labelled approximations: its PSF (diffraction with the lens's Seidel aberrations, axial and lateral
      * colour, at the resolved f-number and focus) through the environment PSF quadrature, its radial distortion, its vignetting
-     * and, for the fisheyes, the equisolid projection. Flare, focus breathing and bokeh shape are not rendered. Not combinable
+     * and, for the fisheyes, the equisolid projection. Flare and focus breathing are not rendered. Not combinable
      * with `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` or `pupilSampling` (the
-     * lens sets them); `defocus` convolves the disc into the lens's PSF. The display view renders it with the PSF taken per field zone (#569; docs/DISPLAY_VIEW.md). Default off.
+     * lens sets them); `defocus` convolves the lens's bokeh kernel (#567) into its PSF. The display view renders it with the PSF taken per field zone (#569; docs/DISPLAY_VIEW.md). Default off.
      * #568: the record form `{ kind: <lens id>, fast }` overrides the top-level `fast` flag for this option; the fast method
      * blends the PSF between exactly resolved kernels on a field grid and tabulates each site's expected signal
      * (docs/LENS_CATALOGUE.md, "Fast method").
@@ -683,7 +713,7 @@ export interface SimulateCaptureOptions {
     exposureCompensationStops?: number;
     /** Default "scene-illuminant". */
     whiteBalance?: SimulateCaptureWhiteBalance;
-    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
+    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 1 (2.20.0; 2 before), the full-quality export. */
     jpegQuantizationStep?: number;
     /** PNG only. Default "srgb". */
     colorEncoding?: SimulateCaptureColorEncoding;
@@ -698,8 +728,13 @@ export interface SimulateCaptureOptions {
     demosaic?: SimulateCaptureDemosaic | SimulateCaptureDemosaicRecord;
     /** Default "margin". */
     borderHandling?: SimulateCaptureBorderHandling;
-    /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
-    dng?: { capturedAtUtc?: string };
+    /**
+     * DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. Opt-in (#587), with
+     * `lens.catalogue`: `lensCorrectionOpcodes` writes the selected corrections of {@link SimulateCaptureLensCorrections} into the DNG as
+     * optional DNG opcodes in OpcodeList3 (FixVignetteRadial, WarpRectilinear with the zoom-to-fill; docs/NATIVE_RAW_AND_PRINT.md), for RAW editors
+     * that apply them; the RAW codes are unchanged. Whole frame only (no `region`). All off (or omitted): the same DNG bytes as without it.
+     */
+    dng?: { capturedAtUtc?: string; lensCorrectionOpcodes?: SimulateCaptureLensCorrections };
     /**
      * Opt-in (2.4) text written into the file for formats "jpeg", "png" and "dng": the caller's description,
      * software, copyright and comment, unchanged (JPEG XMP + COM, PNG tEXt/iTXt, DNG TIFF tags + XMP; see the
@@ -738,10 +773,21 @@ export interface SimulateCaptureOptions {
      * (not the wide-gamut or perceptual PNG paths); not combinable with `region`. The DNG's RAW codes are not changed. Default off.
      */
     sharpening?: SimulateCaptureSharpening;
+    /**
+     * Opt-in (#570), with `lens.catalogue`: the lens's generic corrections (see {@link SimulateCaptureLensCorrections}) on the
+     * developed linear colour, after demosaic, colour, white balance and `diffractionCorrection`, before the tone curve; for the JPEG,
+     * PNG and samples. The RAW and the DNG are never corrected. To keep the output size with no missing pixels, the corrected image is
+     * magnified by the smallest factor 1/m ≥ 1 that keeps every pixel's source inside the frame (recorded in the
+     * `output.lensCorrections` assumption). Works with `region`: a region develops the frame pixels its corrected pixels read
+     * (`region.nativeRect`, `raw` and `plan` describe that rectangle) and its pixels are the whole render's. All off (or omitted):
+     * the development is unchanged.
+     */
+    lensCorrections?: SimulateCaptureLensCorrections;
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
-  sensor?: {
+  /** #555: plus the sensor characteristics ({@link SimulateCaptureSensorCharacteristics}), each off by default. */
+  sensor?: SimulateCaptureSensorCharacteristics & {
     /**
      * 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
@@ -768,15 +814,19 @@ export interface SimulateCaptureOptions {
     pixelAperture?: SimulateCapturePixelAperture;
   };
   /**
-   * Exact or fast (#395). `false` or omitted: every option runs its exact method, the engine reference. `true`: each option
-   * listed in {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of
-   * the exact one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option
-   * only. `diagnostics.fast` reports what was requested and what ran. `lens.catalogue` has a fast method (#568); the other options run exact.
+   * Exact or fast (#395). `false`: every option runs its exact method, the engine reference. `true`: each option listed in
+   * {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of the exact
+   * one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option only.
+   * Omitted (2.20.0), the format decides: fast for `output.format` "srgb-8" and "srgb-16" and for the display view, exact for
+   * "dng", "jpeg" and "png" (exports) and for `simulateIdealReference`. `diagnostics.fast` reports the resolved value, where it
+   * came from and what ran. Fast methods: `lens.catalogue` (#568, #567) and `lens.diffraction` under rolling-shutter rotation
+   * (#565); in the display view also its catalogue PSF zones, its sampling of uniform pixels and its AHD low-signal correction
+   * (docs/DISPLAY_VIEW.md). The exact result also carries `result.sensor.midGrey` (#535). Calculators should pass `fast: false`.
    */
   fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
-  /** Called after each committed RAW, development or JPEG tile. Cannot change output. */
+  /** Called after each committed RAW, development, detail or JPEG tile (see {@link SimulateCaptureProgress}). Cannot change output. */
   onProgress?: (progress: SimulateCaptureProgress) => void;
 }
 ```
@@ -799,11 +849,15 @@ export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samp
 
 ## SimulateCaptureProgress
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+One progress event of `onProgress`. Stages run in this order: `raw`, `white-balance` (with auto white balance), `development`
+(rows), then, when requested, `diffraction-correction` and `sharpening` (#571: one event per output row of the whole image;
+each stage's last event has `completedTileCount === totalTileCount`), then `jpeg`. `output.lensCorrections` (#570) runs between
+`diffraction-correction` and `sharpening` and reports no stage of its own. {@link simulateCaptureFromParts }
+reports no `raw` stage: its RAW comes from the parts.
 
 ```ts
 export interface SimulateCaptureProgress {
-  stage: "raw" | "white-balance" | "development" | "jpeg";
+  stage: "raw" | "white-balance" | "development" | "diffraction-correction" | "sharpening" | "jpeg";
   completedTileCount: number;
   totalTileCount: number;
 }
@@ -963,6 +1017,8 @@ export interface SimulateCaptureResult {
     limitations: readonly string[];
   };
   assumptions: readonly SimulateCaptureAssumption[];
+  /** #555, #535: the sensor characteristics used, the calculated dynamic range and (when the request resolves to exact) the mid-grey noise figure. */
+  sensor: SimulateCaptureSensorReport;
 }
 ```
 

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

@@ -65,9 +65,10 @@ responses through the environment chain, the diffraction kernels, readout moment
 about 0.3–1.3 s per call on a 24 MP request; a region costs only its own pixels. Errors in the request are raised here;
 errors in the view by `render`.
 
-2.11 (#481): `prepareOptions.gpu` chooses the renderer: `"off"` (default) is the CPU reference, today's bytes; `"auto"` renders
+2.11 (#481): `prepareOptions.gpu` chooses the renderer: `"off"` is the CPU reference, today's bytes; `"auto"` renders
 on WebGPU when a conforming device is available and the request is supported, else on the CPU, labelled; `"require"` fails
-instead of falling back (`ImageKernelExecutionError`, acquisition failures here, later ones from `render`). `gpuDevice` is a
+instead of falling back (`ImageKernelExecutionError`, acquisition failures here, later ones from `render`). 2.20.0: the default is
+`"auto"` when the request resolves to fast (the view's default) and `"off"` with `fast: false`. `gpuDevice` is a
 WebGPU entry point or an `ImageKernelAccelerator` whose device the view shares; without it the engine acquires one device
 for the prepared view (the request's `signal` aborts the acquisition) and `dispose()` releases it. The realm's
 `setWebGpuEnabled(false)` vetoes both GPU modes (`webgpu-disabled`). See docs/DISPLAY_VIEW.md, "Rendering on the GPU".

package/docs/api/optics-aperture-diameter.md

@@ -0,0 +1,51 @@
+# optics/aperture-diameter.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.
+
+## ApertureDiameter
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ApertureDiameter {
+  /** Focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** f-number supplied by the caller. */
+  fNumber: number;
+  /** Entrance-pupil diameter D = focalLengthMm / fNumber, in millimetres. */
+  entrancePupilDiameterMm: number;
+}
+```
+
+## calculateApertureDiameter
+
+Entrance-pupil (aperture) diameter in millimetres: focal length ÷ f-number.
+
+Exact by the definition of the f-number for an ideal lens focused at infinity. It is the
+entrance pupil (the aperture stop as seen from the front), not the diaphragm's physical
+opening. Close focus (working f-number N·(1 + m/P) with pupil magnification P) and focal-length
+changes while focusing are not modelled.
+
+Example: 50 mm at f/2 gives 25 mm; at f/4, 12.5 mm (half the diameter, a quarter of the area:
+two stops).
+
+```ts
+export function calculateApertureDiameter(
+  input: CalculateApertureDiameterInput
+): CalculationResult<ApertureDiameter>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateApertureDiameterInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateApertureDiameterInput {
+  /** Focal length of the lens in millimetres (the physical focal length, not a 35 mm equivalent). */
+  focalLengthMm: number;
+  /** f-number set on the lens (N = focal length / entrance-pupil diameter). */
+  fNumber: number;
+}
+```