@photivra/engine 2.19.0 → 2.20.0

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
@@ -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,6 +472,9 @@ 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 }
@@ -557,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").
@@ -700,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;
@@ -715,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
@@ -768,7 +786,8 @@ export interface SimulateCaptureOptions {
   };
   /** 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
@@ -795,10 +814,14 @@ 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. */
@@ -994,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;
+}
+```

package/docs/api/optics-detail-limit.md

@@ -0,0 +1,203 @@
+# optics/detail-limit.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.
+
+## calculateDetailLimit
+
+Which limits detail for given settings: the lens (diffraction at this f-number, aberrations, defocus) or the sensor's pixel
+pitch. Returns the optics' resolution (MTF50 and the diffraction cut-off, cycles/mm), the sampling's (Nyquist frequency
+and, with a Bayer filter, the red and blue sites'), the system MTF50 (optics × pixel aperture), the f-number from which
+diffraction limits on this sensor, and which one limits.
+
+The sensor limits when the optics still pass 50 % contrast at the Nyquist frequency 1/(2p); otherwise the lens does,
+through diffraction when its wavefront error is within the Maréchal criterion (RMS ≤ λ/14), else through aberrations or
+defocus. The optics MTF is the exact scalar OTF of the stated wavefront at one wavelength; the decision rule and the
+catalogue lenses' wavefronts are approximations.
+
+Example: an ideal 50 mm lens at f/22 on a 36 × 24 mm, 6000-pixel-wide sensor (6 µm) is limited by diffraction (optics
+MTF50 ≈ 33 cycles/mm against a Nyquist frequency of ≈ 83); at f/4 the pixel pitch limits.
+
+```ts
+export function calculateDetailLimit(input: CalculateDetailLimitInput): CalculationResult<DetailLimit>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDetailLimitInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDetailLimitInput {
+  /** Active imaging area and horizontal pixel count; pitch = widthMm / pixelWidth. */
+  sensor: {
+    widthMm: number;
+    heightMm: number;
+    pixelWidth: number;
+    /** Default `"bayer"`. `"none"`: every site records full detail (a monochrome sensor). */
+    colorFilterArray?: "bayer" | "none";
+  };
+  lens: DetailLimitIdealLens | DetailLimitCatalogueLens;
+  /** f-number set on the lens. */
+  fNumber: number;
+  /**
+   * Focus and subject distances from the lens in meters. Omitted: focused at infinity, subject in focus. `subjectDistanceM`
+   * omitted: the subject is at the focus distance.
+   */
+  focus?: { focusDistanceM: number; subjectDistanceM?: number };
+  /** Field height as a fraction of the half-diagonal, 0 (center, default) to 1 (corner). Only aberrations depend on it. */
+  fieldPosition?: number;
+  /** Wavelength in nanometres, 380–780. Default 550. */
+  wavelengthNm?: number;
+}
+```
+
+## DETAIL_LIMIT_LIMITS
+
+Limits of `calculateDetailLimit`: the wavelength range and the largest wavefront (sum of the magnitudes of its terms, in
+waves) whose transfer function is integrated. Beyond it the blur is geometric and the quadrature would grow without
+bound; use `calculateDefocusCircle` for such a blur.
+
+```ts
+DETAIL_LIMIT_LIMITS = Object.freeze({ minimumWavelengthNm: 380, maximumWavelengthNm: 780, maximumWavefrontWaves: 64 })
+```
+
+## DetailLimit
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimit {
+  /** The lens or the sensor. */
+  limitedBy: DetailLimitedBy;
+  /** Diffraction, aberrations or defocus (the lens), or the pixel pitch (the sensor). */
+  limitingFactor: DetailLimitingFactor;
+  /** Optics MTF50 / Nyquist frequency: at least 1 when the sensor limits. */
+  opticsToNyquistRatio: number;
+  fNumber: number;
+  wavelengthNm: number;
+  /** Physical focal length used (the catalogue lens's on this sensor), mm. */
+  focalLengthMm: number;
+  fieldPosition: number;
+  optics: DetailLimitOptics;
+  sampling: DetailLimitSampling;
+  system: DetailLimitSystem;
+  /**
+   * The f-number at which an aberration-free lens in focus has its MTF50 at the Nyquist frequency (2·p·0.40397/λ at
+   * infinity focus): from it on, diffraction limits detail on this sensor whatever the lens.
+   */
+  diffractionLimitedFNumber: number;
+  basis: Readonly<Record<"optics" | "sampling" | "system" | "limitedBy", DetailLimitBasis>>;
+}
+```
+
+## DetailLimitBasis
+
+Whether a quantity is exact under its stated conditions or an approximation.
+
+```ts
+export interface DetailLimitBasis { kind: "exact" | "approximation"; statement: string }
+```
+
+## DetailLimitCatalogueLens
+
+A generic catalogue lens (`GENERIC_LENS_IDS`), resolved for the sensor as `resolveGenericLens` does.
+
+```ts
+export interface DetailLimitCatalogueLens {
+  kind: "catalogue";
+  lensId: string;
+}
+```
+
+## DetailLimitedBy
+
+Which component limits detail.
+
+```ts
+export type DetailLimitedBy = "lens" | "sensor";
+```
+
+## DetailLimitIdealLens
+
+A lens with no aberrations (diffraction only).
+
+```ts
+export interface DetailLimitIdealLens {
+  kind: "ideal";
+  /** Physical focal length in millimeters (for the working f-number and the defocus of a subject off the focus distance). */
+  focalLengthMm: number;
+}
+```
+
+## DetailLimitingFactor
+
+What limits it: the lens's diffraction, aberrations or defocus, or the sensor's pixel pitch.
+
+```ts
+export type DetailLimitingFactor = "diffraction" | "aberrations" | "defocus" | "pixel-pitch";
+```
+
+## DetailLimitOptics
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitOptics {
+  /** Working f-number N_w = N·v/f (thin-lens image distance v; N at infinity focus). */
+  workingFNumber: number;
+  /** Diffraction cut-off 1/(λ·N_w) in cycles/mm: no optics passes detail beyond it. */
+  cutoffCyclesPerMm: number;
+  /** Frequency where the optics' MTF falls to 0.5, the lower of the two directions, cycles/mm. */
+  mtf50CyclesPerMm: number;
+  /** MTF50 for detail along the radius from the image center (tangential), cycles/mm. */
+  tangentialMtf50CyclesPerMm: number;
+  /** MTF50 for detail across the radius (sagittal), cycles/mm. Equal to the tangential value at the center. */
+  sagittalMtf50CyclesPerMm: number;
+  /** MTF50 of an aberration-free lens in focus at the same working f-number (0.40397·cut-off), cycles/mm. */
+  diffractionMtf50CyclesPerMm: number;
+  /** Optics MTF at the sensor's Nyquist frequency (lower direction). */
+  mtfAtNyquist: number;
+  /** RMS wavefront error in waves at the wavelength: of the aberrations, of the defocus, and of both together. */
+  rmsWavefrontErrorWaves: { aberrations: number; defocus: number; total: number };
+  /** Whether the total RMS wavefront error is within the Maréchal criterion λ/14. */
+  withinMarechalCriterion: boolean;
+  /** Geometric blur-circle diameter of the defocus on the sensor, mm (0 in focus). */
+  defocusBlurDiameterMm: number;
+}
+```
+
+## DetailLimitSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitSampling {
+  colorFilterArray: "bayer" | "none";
+  /** Pixel pitch in micrometres: widthMm / pixelWidth. */
+  pixelPitchMicrometers: number;
+  /** 1/(2p), cycles/mm: the finest detail the pixel grid records without aliasing (Bayer green sites too, along rows and columns). */
+  nyquistCyclesPerMm: number;
+  /** Bayer only: 1/(4p), the Nyquist frequency of the red and blue sites. Null without a color filter array. */
+  redBlueNyquistCyclesPerMm: number | null;
+  /** Pixel aperture MTF at the Nyquist frequency: sinc(1/2) = 2/π. */
+  pixelApertureMtfAtNyquist: number;
+  /** Frequency where the pixel aperture MTF falls to 0.5 (0.60335/p), cycles/mm: beyond the Nyquist frequency. */
+  pixelApertureMtf50CyclesPerMm: number;
+}
+```
+
+## DetailLimitSystem
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitSystem {
+  /** MTF50 of optics × pixel aperture (lower direction), cycles/mm. Detail above the Nyquist frequency aliases. */
+  mtf50CyclesPerMm: number;
+  /** The same in line pairs per picture height (cycles/mm × heightMm). */
+  mtf50LinePairsPerPictureHeight: number;
+  /** System MTF at the Nyquist frequency (lower direction). */
+  mtfAtNyquist: number;
+}
+```

package/docs/api/output-crop-to-match-focal-length.md

@@ -0,0 +1,67 @@
+# output/crop-to-match-focal-length.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.
+
+## calculateCropToMatchFocalLength
+
+The centred crop that makes an image from a shorter lens match a longer lens's framing from the
+same position: crop factor target ÷ focal length, and the pixels and megapixels left.
+
+Exact for ideal rectilinear lenses focused at infinity, to whole pixels (the crop is
+`calculateCenteredCrop`'s, which keeps the aspect ratio). At close focus the matching factor is
+larger, F·(d − f)/(f·(d − F)) at object distance d (thin lens); that, distortion and focus
+breathing are not modelled. The crop has the longer lens's framing and perspective but fewer
+pixels: it records no more detail than the cropped part of the shorter lens's image.
+
+Example: a 24 MP (6000 × 4000) image at 50 mm cropped to match 100 mm: factor 2, 3000 × 2000,
+6 MP.
+
+```ts
+export function calculateCropToMatchFocalLength(
+  input: CalculateCropToMatchFocalLengthInput
+): CalculationResult<CropToMatchFocalLength>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCropToMatchFocalLengthInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCropToMatchFocalLengthInput {
+  /** Focal length the image was taken with, in millimetres. */
+  focalLengthMm: number;
+  /** Longer focal length whose framing the crop should match, in millimetres. At least `focalLengthMm`. */
+  targetFocalLengthMm: number;
+  /** Image width in pixels (for example the sensor's output width). */
+  pixelWidth: number;
+  /** Image height in pixels. */
+  pixelHeight: number;
+}
+```
+
+## CropToMatchFocalLength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CropToMatchFocalLength {
+  /** Focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** Target focal length supplied by the caller, in millimetres. */
+  targetFocalLengthMm: number;
+  /** Linear crop factor targetFocalLengthMm / focalLengthMm (1 means no crop). */
+  cropFactor: number;
+  /** Width left after the centred crop, in pixels (as `calculateCenteredCrop`). */
+  pixelWidth: number;
+  /** Height left after the centred crop, in pixels. */
+  pixelHeight: number;
+  /** Pixels left, in millions. */
+  megapixels: number;
+  /** Megapixels of the uncropped image. */
+  sourceMegapixels: number;
+  /** Fraction of the original pixel area retained, about 1 / cropFactor². */
+  retainedAreaFraction: number;
+}
+```

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

@@ -6,7 +6,9 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 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). The result passes `parseGenericLensCorrectionProfile`.
+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;

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

@@ -31,7 +31,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 ## calculatePeripheralIlluminationCorrection
 
 Applies a gain after capture and reports the variance before clipping. It does not rewrite
-the photon or SNR (signal-to-noise ratio) history of the capture.
+the photon or SNR (signal-to-noise ratio) history of the capture. The gain is T^(−strength), T the relative illumination at
+`imagePointMm`: E(ρ) of the component's profile, divided by det J(ρ_i) when the component has a `distortionAreaFactor` (#584;
+then `imagePointMm` is the capture's sensor point, where the capture applied both).
 
 ```ts
 export function calculatePeripheralIlluminationCorrection(input: {
@@ -77,6 +79,14 @@ export interface IlluminationLensCorrection extends CorrectionComponentIdentity
   kind: "peripheral-illumination";
   profile: IlluminationVignettingProfile;
   strength: number;
+  /**
+   * Optional (#584): the capture's radial distortion r_d = r(1 + k1ρ² + k2ρ⁴ + k3ρ⁶), whose area factor 1/det J the capture also
+   * multiplied into the irradiance (det J = (1 + k1ρ_i² + k2ρ_i⁴ + k3ρ_i⁶)(1 + 3k1ρ_i² + 5k2ρ_i⁴ + 7k3ρ_i⁶) at the ideal point ρ_i that
+   * the lens images to the sensor point). With it, the relative illumination corrected is E(ρ_s)/det J(ρ_i), evaluated at the
+   * capture's sensor (source) point, so strength 1 flattens a flat field. It holds whether or not the distortion itself is corrected.
+   * Without it the gain is 1/E alone, as before.
+   */
+  distortionAreaFactor?: RadialDistortionProfile;
 }
 ```