@photivra/engine 2.19.0 → 2.21.0

package/THIRD_PARTY.md

@@ -31,21 +31,28 @@ This inventory does not replace a transitive dependency/SBOM review before a rel
 
 ## Pending licence and source reviews
 
-These human reviews are **pending**. This inventory records them and the evidence for each; it does not complete them. A review is complete only when the owner signs it off: a check by an AI system is not legal evidence (`CONTRIBUTING.md`). Each is described in full in its section below.
+These human reviews were **pending** until the owner signed all five off on 2026-11-09 (#544; see the status below). This inventory records them and the evidence for each. A review is complete only when the owner signs it off: a check by an AI system is not legal evidence (`CONTRIBUTING.md`). Each is described in full in its section below.
+
+**Status on 2026-11-09.** The owner signed off all five reviews on [#544](https://github.com/Photivra/photivra/issues/544) on 2026-11-09: "castleCSF-derived contrast reference", "ReportLab/pypdf offline PDF test-artifact tools", "DNG/TIFF and JPEG sample provenance", "Colorimetry published constants", and "Transitive dependency / SBOM review" for 2.14.0–2.19.0 (from 2.20.0 that review is repeated for each release's exact lockfile, with the `npm run check:licenses` result and any new or changed licence listed in the release's pull request).
 
 **Status on 2026-11-02.** 2.14.0 was tagged and published to npm with the owner's approval ([release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_14_0.md)) while these five reviews were open. **The owner accepted 2.14.0 shipping with these reviews open, 2026-11-02.** None of them is signed off. What each still needs is tracked in [#544](https://github.com/Photivra/photivra/issues/544). The evidence below was checked on 2026-11-02 against `main` at `v2.14.0` (`f4b09a7`), using the repository's own records.
 
 | Review | Evidence checked on 2026-11-02 | Still needed from the owner |
 | --- | --- | --- |
-| castleCSF-derived contrast reference (`src/output/print-contrast-reference.ts`) | **Licence evidence complete.** The MIT text in `NOTICE` is identical to `docs/licenses/castleCSF-MIT.txt`. A licence-compliance pass on 2026-11-02 compared that file with upstream `LICENSE` at revision `f4b0b722af83001d7af979281e06ca642d36e4e8` through the GitHub API: identical. The adapter's header names the holder and is kept in the published `dist/output/print-contrast-reference.js`. | Sign-off of the licence summary, and the separate scientific/source review ([the model/protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_CONTRAST_REFERENCE.md)), including whether upstream holds the model material under other terms. |
-| ReportLab/pypdf offline PDF test-artifact tools | The committed `output/pdf/print-proof-reference.pdf` has no `FontFile` entry and declares only `/BaseFont /Helvetica`, so no font program is embedded. The versions used are recorded as ReportLab 4.4.9 and pypdf 6.10.0 (`test/fixtures/print-detail/proof-layout-reference.json`, `proof-inspection-reference.json`, `docs/validation/print-196-candidate-evidence.json`). Neither tool is vendored or in the package. **Not verified:** the licence files of those exact versions (not installed locally). | The substantive human source review. |
-| DNG/TIFF and JPEG sample provenance | All 26 tracked `.dng`/`.jpg` files name only "Photivra", "Photivra Virtual Camera" or "Photivra Print JPEG" (`strings` scan); no camera maker's name appears. The Adobe DNG notice is in `NOTICE`, `README.md` and the three DNG sources. **Not done:** byte-for-byte regeneration of the files. | The provenance/licence review. |
-| Transitive dependency/SBOM review | **Evidence complete for the 2.14.0 lockfile.** Recount of `package-lock.json`: 168 entries, with the licence counts given in [its summary](#per-release-transitive-dependency--sbom-review); no entry is a runtime dependency. `npm run check:licenses` passes. GitHub reports MIT for all four GitHub Actions in the table above (their repositories' detected licence). | Sign-off for 2.14.0. The review is repeated for each release's exact lockfile. |
-| Colorimetry published constants (`src/color/`). See [Colorimetry published constants and excluded datasets](#colorimetry-published-constants-and-excluded-datasets). | No CIE table is committed: the largest set of decimal constants in `src/color/` is 37, in `color-matching-functions.ts` (the engine's own fit). Each constant's source is cited in that section. The primary sources were not re-read in this check. | The human source/licence review of each cited source. |
+| castleCSF-derived contrast reference (`src/output/print-contrast-reference.ts`) | **Licence evidence complete.** The MIT text in `NOTICE` is identical to `docs/licenses/castleCSF-MIT.txt`. A licence-compliance pass on 2026-11-02 compared that file with upstream `LICENSE` at revision `f4b0b722af83001d7af979281e06ca642d36e4e8` through the GitHub API: identical. The adapter's header names the holder and is kept in the published `dist/output/print-contrast-reference.js`. | **Signed off by the owner, 2026-11-09** (#544), after a scientific and source review: the adapter matches the pinned upstream code in every constant and step of its restricted domain (relative difference at most 3.8e-9, and 1.7e-15 against the 80-digit reference); where the paper's printed Eq. 21–22 differ from the code, the code wins ([the model/protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_CONTRAST_REFERENCE.md)). |
+| ReportLab/pypdf offline PDF test-artifact tools | The committed `output/pdf/print-proof-reference.pdf` has no `FontFile` entry and declares only `/BaseFont /Helvetica`, so no font program is embedded. The versions used are recorded as ReportLab 4.4.9 and pypdf 6.10.0 (`test/fixtures/print-detail/proof-layout-reference.json`, `proof-inspection-reference.json`, `docs/validation/print-196-candidate-evidence.json`). Neither tool is vendored or in the package. The licences of the exact versions were checked on 2026-11-09: ReportLab 4.4.9 is BSD ("BSD license", ReportLab Inc.; PyPI metadata; the `LICENSE` text was read from an unofficial mirror, unchanged since 2024-12-17) and pypdf 6.10.0 is BSD-3-Clause (PyPI metadata and the `LICENSE` at the pypdf `6.10.0` tag). The PDF embeds no library code or font program, and neither licence sets conditions on output made with the software, so no notice is owed for the generated artifact. Pillow (a ReportLab dependency, used to read the JPEG header; the bytes pass through unchanged) was also present when it was generated; its version was not recorded. | **Signed off by the owner, 2026-11-09** (#544). |
+| DNG/TIFF and JPEG sample provenance | All 26 tracked `.dng`/`.jpg` files name only "Photivra", "Photivra Virtual Camera" or "Photivra Print JPEG" (`strings` scan); no camera maker's name appears. The Adobe DNG notice is in `NOTICE`, `README.md` and the three DNG sources. **Not done:** byte-for-byte regeneration of the files. | **Signed off by the owner, 2026-11-09** (#544). |
+| Transitive dependency/SBOM review | **Evidence complete for the 2.14.0 lockfile.** Recount of `package-lock.json`: 168 entries, with the licence counts given in [its summary](#per-release-transitive-dependency--sbom-review); no entry is a runtime dependency. `npm run check:licenses` passes. GitHub reports MIT for all four GitHub Actions in the table above (their repositories' detected licence). | **Signed off by the owner for 2.14.0–2.19.0, 2026-11-09** (#544). From 2.20.0 it is reviewed per release: each release's pull request gives the `npm run check:licenses` result and any new or changed licence against the previous release's lockfile. |
+| Colorimetry published constants (`src/color/`). See [Colorimetry published constants and excluded datasets](#colorimetry-published-constants-and-excluded-datasets). | No CIE table is committed: the largest set of decimal constants in `src/color/` is 37, in `color-matching-functions.ts` (the engine's own fit). Each constant's source is cited in that section. On 2026-11-09 every constant was re-read against its free source (paywalled primaries through free secondaries, and numerically against the free CIE datasets), with no mismatch. | **Signed off by the owner, 2026-11-09** (#544). |
+| Sensor profile sources (#554, `src/equipment/sensor-profiles.ts`). See [Sensor profile sources](#sensor-profile-sources-554). | **Signed off by the owner on 2026-11-09** (sources approved as listed; astronomy-camera manuals accepted for sensor values only; the retailer copy for one profile accepted, labelled; links allowed in `docs/SENSOR_PROFILES.md` only). Ten free sources and three standards (ISO 12232 labelled paywalled); every value is labelled published, derived or design. | Nothing for #554. |
+
+## Sensor profile sources (#554)
+
+`src/equipment/sensor-profiles.ts` holds eight sensor profiles whose values are facts taken from manufacturer-published specifications (sensor dimensions, pixel counts, pixel pitch, full well, read noise, peak QE, ADC bit depth, frame rate) and one openly published paper (International Image Sensor Workshop 2017, paper R03, Table 1), or Photivra design values labelled as such. They are factual references (`reuseStatus: "factual-reference-only"`); no table, curve, image or text is copied, and no maker or product is named in the code, data or docs. Commercial or terms-restricted measurement databases and test websites were excluded and not used (owner decision, 2026-11-06). ISO 12232:2019 is named for a cross-check only; no value depends on it. Sources, with links, and derivations: `docs/SENSOR_PROFILES.md`. The owner signed off the source review on 2026-11-09 (table above).
 
 ## Licence summaries (prepared for owner sign-off)
 
-Prepared on 2026-10-11 from local files only (repository files, `package-lock.json` and locally installed package metadata). These are factual summaries for the owner to sign off; they are **not** completed reviews, and every item above stays pending until the owner signs it off (see the status above: 2.14.0 was released with them open). "Not verified" means the fact could not be checked locally.
+Prepared on 2026-10-11 from local files only (repository files, `package-lock.json` and locally installed package metadata). These are factual summaries for the owner to sign off; they are **not** completed reviews, and each item above stayed pending until the owner signed it off (2.14.0 was released with them open; all five were signed off on 2026-11-09). "Not verified" means the fact could not be checked locally.
 
 ### castleCSF-derived contrast reference
 
@@ -62,7 +69,7 @@ Prepared on 2026-10-11 from local files only (repository files, `package-lock.js
 - **Permissions:** both licences permit commercial use, modification and redistribution in source and binary form.
 - **Obligations:** keep the copyright notice, conditions and disclaimer on redistribution, and do not use the contributors' names for endorsement. Neither tool is vendored or redistributed here, so no notice is currently owed.
 - **Concerns:**
-  - The installed versions are ReportLab 5.0.1 and pypdf 6.17.0. The versions recorded for the committed artifact (ReportLab 4.4.9, pypdf 6.10.0) are not installed locally, so their exact licence files are not verified.
+  - The licences of the exact versions were checked on 2026-11-09: ReportLab 4.4.9 is BSD ("BSD license", ReportLab Inc.; PyPI metadata; the `LICENSE` text was read from an unofficial mirror, unchanged since 2024-12-17) and pypdf 6.10.0 is BSD-3-Clause (PyPI metadata and the `LICENSE` at the pypdf `6.10.0` tag). The PDF embeds no library code or font program, and neither licence sets conditions on output made with the software, so no notice is owed for the generated artifact. Pillow (a ReportLab dependency, used to read the JPEG header; the bytes pass through unchanged) was also present when it was generated; its version was not recorded.
   - The ReportLab distribution also bundles font files, including DarkGarden (with a GPL copying file) and Vera. The committed `output/pdf/print-proof-reference.pdf` contains no `FontFile` entries and declares only `/BaseFont /Helvetica`, so no bundled font program is embedded (checked locally).
 
 ### DNG/TIFF and JPEG sample provenance
@@ -97,9 +104,13 @@ The colorimetry modules in `src/color/` (see [docs/COLORIMETRY.md](https://githu
 | --- | --- | --- |
 | 28 coefficients of the engine's own multi-lobe CIE 1931 CMF fit (`color-matching-functions.ts`) | Fitted by Photivra with `scripts/fit-cie-1931-cmf.mjs` to the CIE 1931 2° table, DOI 10.25039/CIE.DS.xvudnb9b (CIE, CC BY-SA 4.0). The model form, a sum of piecewise Gaussians, follows the idea in Wyman, Sloan & Shirley (2013), JCGT 2(2); none of that paper's coefficients or text are used. | Fit-time use only: the script downloads the table into a temporary directory outside the repository, checks its SHA-256 and deletes it. No CIE value is stored in the repository, the package, the tests or the script's output. The committed coefficients are our own least-squares result; 28 numbers cannot reproduce the 1,413-value table (maximum error 0.022). Attribution to the CIE dataset is given here and in `docs/COLORIMETRY.md`. Replaced the Wyman et al. coefficients by owner decision (2026-10-17). |
 | Reference CIELAB and sRGB values of the engine's own color patches (`color-patches.ts`, `docs/COLOR_PATCHES.md`) | Computed by Photivra with `scripts/compute-color-patch-reference.mjs` from Photivra's own analytic spectra, using the CIE standard illuminant D65 table (DOI 10.25039/CIE.DS.hjfjmt59) and the CIE 1931 2° table (DOI 10.25039/CIE.DS.xvudnb9b), both CIE, CC BY-SA 4.0. The spectra themselves are Photivra's design; no ColorChecker, IT8 or other commercial target data, names, order or layout are used. | Computation-time use only, as for the CMF fit: the script downloads both tables into a temporary directory, checks their SHA-256 and deletes them. No CIE value is stored in the repository, the package, the tests or the script's output; the committed values (three CIELAB coordinates and one 8-bit sRGB colour per patch) are results computed from our spectra. Attribution to the CIE datasets is given here and in `docs/COLOR_PATCHES.md`. |
+| Node spectra of the image-plane scene's print reflectance lattice (`image-plane-lattice-data.ts`, `docs/IMAGE_PLANE.md`, #581) | Fitted by Photivra with `scripts/fit-image-plane-lattice.mjs`: the LHTSS method of S. A. Burns, "Generating Reflectance Curves from sRGB Triplets", arXiv:1710.05732 v5 (2020), pp. 24–26 (the paper is CC BY-SA 4.0; its method is implemented from the equations, and neither its text nor its MATLAB code, also CC BY-SA 4.0, is used), against the CIE standard illuminant D65 table (DOI 10.25039/CIE.DS.hjfjmt59, https://files.cie.co.at/Publications-datasets/CIE_std_illum_D65.csv) and the CIE 1931 2° table (DOI 10.25039/CIE.DS.xvudnb9b, https://files.cie.co.at/Publications-datasets/CIE_xyz_1931_2deg.csv), both CIE, CC BY-SA 4.0. Owner decision 2026-11-09 (#581). | Fit-time use only, as for the CMF fit: the script downloads both tables into a temporary directory outside the repository, checks their SHA-256 and deletes them. No CIE value is stored in the repository, the package, the tests or the script's output. The committed data (120 spectra × 41 samples of 16 bits, delta-coded) are Photivra's own optimization results: each is the smoothest bounded spectrum that meets three integral constraints, and they cannot reproduce the tables. Attribution to the CIE datasets is given here and in `docs/IMAGE_PLANE.md`. |
+| Representative light-source spectra (`representative-light-sources.ts`, `docs/LIGHT_SOURCES.md`, #557) | Photivra's own design (owner decision 2026-11-06): a constant plus Gaussian bands whose positions and widths Photivra chose for each kind of lamp, with two parameters per source solved by Photivra to put it on the Planckian locus at its stated CCT using the engine's own analytic CMF fit and Planck's law. No third-party spectral data is used: no CIE illuminant tables (the F-series fluorescent, LED-series or any other), no IES TM-30 or CIE test-sample reflectances, and no manufacturer or product spectra, names or data sheets. Their CCT and color-rendering figures are computed with the engine's own code and color patches only. | Photivra's own work under the project licence; nothing to attribute. Labeled "representative, not a named product". |
 | Distinctness check of the color patches' published colors and names (`scripts/check-color-patch-distinctness.mjs`, `docs/COLOR_PATCHES.md`) | Reference colors compared against, each downloaded from a pinned URL and checked by SHA-256: the CSS named colors (W3C, CSS Color Module Level 4, CRD 2025-04-24; W3C Software and Document License, as linked from that document); the ColorChecker Classic's manufacturer sRGB values as tabulated in Wikipedia, "ColorChecker", revision 1367818471 (CC BY-SA 4.0); the ColorChecker's published X-Rite (before and after November 2014), GretagMacbeth 2005 and BabelColor average values as collected in colour-science 0.4.6 (BSD-3-Clause); RAL Classic approximate sRGB values as tabulated in Wikipedia, "List of RAL colours", revision 1369650571 (CC BY-SA 4.0); brand colors from Simple Icons 1.20.0, 2.19.0, 4.25.0, 9.21.0 and 16.36.0 (its data is dedicated to the public domain). Pantone data is proprietary and is not used. | Check-time use only: the script parses each source in memory, compares it with Photivra's own values and discards it. No third-party color value, name or table is stored in the repository, the package, the tests or the script's output, apart from what the script prints and `docs/COLOR_PATCHES.md` reports per patch as a factual result: the closest reference color's name, its set, its 8-bit sRGB hex (the "Its sRGB" column, one value per patch, 30 in all) and the ΔE00. The "Nudged patches" table there also names the reference colors the first design was too close to. `docs/COLOR_PATCHES.md` is repository documentation and is not in the npm package. The 30 hex values are attributed under its Result table: 7 ColorChecker and 6 RAL Classic values copied unchanged from the Wikipedia tables (CC BY-SA 4.0, credited with the title, authors, revision link and licence link that CC BY-SA 4.0 §3(a) asks for), 1 ColorChecker value converted to sRGB by the script from colour-science 0.4.6's CIELAB data (BSD-3-Clause, by the Colour Developers), 2 CSS named colors (W3C) and 14 Simple Icons brand colors (CC0 1.0). The patch names and colors are Photivra's own; the check only confirms that they differ. |
 | Daylight-locus polynomial and M₁/M₂ coefficients; illuminant A formula constants; CIELAB, CIE94 and CIEDE2000 formula constants (`illuminants.ts`, `color-difference.ts`) | CIE 15:2018 (daylight and illuminant A constants; values checked against the free CIE datasets); CIELAB as in W3C CSS Color 4; CIE94 as stated in Wikipedia, "Color difference" (secondary source; the primary CIE 116-1995 is not free); Sharma, Wu & Dalal (2005), also CIE 142-2001 | Coefficients of standardized equations, used as factual constants. |
 | McCamy CCT cubic | McCamy (1992), Color Res. Appl. 17(2) | Published equation coefficients. |
+| CIE 1960 UCS (u, v) formulas: u = 4x/(−2x + 12y + 3), v = 6y/(−2x + 12y + 3) and their inverse (`colorimetry-math.ts`) | CIE 15 (the CIE 1960 UCS definition; paywalled, checked through the free secondary Wikipedia, "CIE 1960 color space") | Standard definitional formula constants (added to this inventory 2026-11-09, #544). |
+| The 4-decimal sRGB → XYZ matrix in the GPU display-view test fixture (`src/gpu/display-view-quality-gpu.ts`, its `ahdCorrection.labMatrix`) | Derived from the ITU-R BT.709-6 primaries and the D65 white point (free); it equals the 4-decimal matrix of IEC 61966-2-1 | Standardized constants derived from free sources (added to this inventory 2026-11-09, #544). |
 | Bradford and CAT16 matrices (`chromatic-adaptation.ts`) | Lam (1985) / ICC.1:2010 Annex E; CAT16: Li et al. (2016), IS&T CIC24, Eq. (15), doi:10.2352/ISSN.2169-2629.2017.32.208 (free; checked 2026-10-17 to match the engine; journal version Li et al. 2017) | Published 3×3 model constants. CAT02, the Hunt–Pointer–Estévez matrix and the CIECAM02 degree-of-adaptation formula were removed from 2.0 (owner decisions, 2026-10-17) because no confirmed free source prints them. |
 | Primaries and white points; BT.709 and BT.1886 constants (`rgb-color-spaces.ts`) | ITU-R BT.709-6, BT.1886, BT.2020-2; W3C CSS Color 4 (`srgb`, `display-p3`); also IEC 61966-2-1, SMPTE EG 432-1 | Standardized numeric constants; every value is available from the freely published ITU-R and W3C documents. |
 | h, c, k | BIPM SI Brochure (2019) | Exact SI defining constants (facts). |
@@ -148,14 +159,14 @@ The Malvar–He–Cutler demosaic kernels and their parameters, and the BT.2408
 
 The original scalar adapter in `src/output/print-contrast-reference.ts` uses numerical equations/parameters from [castleCSF revision f4b0b722af83001d7af979281e06ca642d36e4e8](https://github.com/gfxdisp/castleCSF/tree/f4b0b722af83001d7af979281e06ca642d36e4e8): `matlab/CSF_castleCSF.m`, `CSF_stelaCSF_lum_peak.m`, `CSF_castleCSF_chrom.m` and `CSF_base.m`. The upstream code/model material is MIT-licensed, copyright (c) 2023 Graphics and Displays group - University of Cambridge. The exact license is preserved at `docs/licenses/castleCSF-MIT.txt` and its notice is retained in `NOTICE` and adapter source. New TypeScript/reference code is distributed under the project Apache-2.0 terms while retaining the MIT notice for upstream numerical material.
 
-No upstream observational CSV, paper text/figure/table, color-matching dataset or runtime dependency is incorporated. The model's presence does not certify camera, print, observer or natural-image visibility applicability. [The model/protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_CONTRAST_REFERENCE.md) records the restricted envelope, independent numerical evaluation and pending human scientific/source/license review. The root still declares no runtime npm dependencies.
+No upstream observational CSV, paper text/figure/table, color-matching dataset or runtime dependency is incorporated. The model's presence does not certify camera, print, observer or natural-image visibility applicability. [The model/protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_CONTRAST_REFERENCE.md) records the restricted envelope, independent numerical evaluation and the scientific/source/licence review the owner signed off on 2026-11-09 (#544). The root still declares no runtime npm dependencies.
 
 
 ## Optional offline physical-proof tools
 
 The optional repository-only QA scripts `scripts/verify-photographic-export-fixtures.py` and `scripts/verify-producer-export-acceptance.py` load an installed LibRaw (LGPL-2.1 or CDDL-1.0) dynamically through its C API. Nothing from LibRaw is copied or distributed, and the scripts are not part of the package.
 
-The owned PDF geometry reference is generated with ReportLab 4.4.9 and independently inspected with pypdf 6.10.0. Their installed distribution license files were reviewed as BSD-3-Clause-style terms (ReportLab metadata calls its license BSD; pypdf declares BSD-3-Clause). These are optional offline test-artifact tools, not runtime/npm dependencies. No library source, binary or embedded font program is vendored. The PDF preserves existing owned JPEG streams and uses the PDF standard Helvetica font declaration; its DeviceRGB appearance and actual printing remain unqualified. Generator/parser versions and artifact hashes are retained in the candidate evidence record. Substantive human source review remains pending.
+The owned PDF geometry reference is generated with ReportLab 4.4.9 and independently inspected with pypdf 6.10.0. The licences of the exact versions were checked on 2026-11-09: ReportLab 4.4.9 is BSD ("BSD license", ReportLab Inc.; PyPI metadata; the `LICENSE` text was read from an unofficial mirror, unchanged since 2024-12-17) and pypdf 6.10.0 is BSD-3-Clause (PyPI metadata and the `LICENSE` at the pypdf `6.10.0` tag). The PDF embeds no library code or font program, and neither licence sets conditions on output made with the software, so no notice is owed for the generated artifact. Pillow (a ReportLab dependency, used to read the JPEG header; the bytes pass through unchanged) was also present when it was generated; its version was not recorded. These are optional offline test-artifact tools, not runtime/npm dependencies. No library source, binary or embedded font program is vendored. The PDF preserves existing owned JPEG streams and uses the PDF standard Helvetica font declaration; its DeviceRGB appearance and actual printing remain unqualified. Generator/parser versions and artifact hashes are retained in the candidate evidence record. The owner signed off this review on 2026-11-09 (#544).
 
 ## Automated license policy
 

package/dist/capture/dng-lens-correction-opcodes.d.ts

@@ -0,0 +1,32 @@
+import { prepareDevelopedLensCorrection, type ChannelDispersion, type DevelopedLensCorrectionSelection } from "../output/developed-lens-corrections.js";
+/** @internal An opcode as written (application order), for the assumptions. */
+export type DngLensCorrectionOpcode = 
+/** k0…k4 of g = 1 + k0r² + … + k4r¹⁰, and the largest |g/G − 1| on 2 048 radii in [0, 1]. */
+{
+    opcode: "FixVignetteRadial";
+    coefficients: number[];
+    maximumRelativeFitError: number;
+}
+/** kr0…kr3, kt0, kt1 of one plane (all channels) or red, green, blue; the zoom-to-fill 1/m folded into kr0. */
+ | {
+    opcode: "WarpRectilinear";
+    planes: number[][];
+    magnification: number;
+};
+/** @internal Largest accepted |g/G − 1| of the FixVignetteRadial fit. */
+export declare const DNG_VIGNETTE_FIT_TOLERANCE = 0.001;
+/**
+ * @internal The OpcodeList3 bytes and the opcodes for a catalogue lens (`resolveGenericLens` at the capture's f-number, on the
+ * W × H ActiveArea of pitch `pitchMm`) and the selected corrections, at least one on (see the module notes).
+ */
+export declare function createDngLensCorrectionOpcodes(lens: Parameters<typeof prepareDevelopedLensCorrection>[0] & {
+    name: string;
+    character: {
+        vignetting: {
+            cornerStops: number;
+        };
+    };
+}, selection: DevelopedLensCorrectionSelection, width: number, height: number, pitchMm: number, channels: ChannelDispersion): {
+    opcodeList3: Uint8Array;
+    opcodes: DngLensCorrectionOpcode[];
+};

package/dist/capture/dng-lens-correction-opcodes.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+// This product includes DNG technology under license by Adobe.
+/**
+ * @internal #587: a catalogue lens's generic corrections (`createGenericLensCorrectionProfile`, the same arithmetic as `output.lensCorrections`)
+ * written as a DNG opcode list, so a RAW editor that applies DNG opcodes corrects the DNG non-destructively; the RAW codes are never
+ * changed. Written from the Adobe DNG Specification (opcode lists were added in version 1.3.0.0; the repository's writer follows
+ * 1.7.1.0), chapter "Opcode List Processing":
+ *
+ * - The list goes into OpcodeList3 (tag 51022, UNDEFINED), which a reader applies to the linear, demosaiced stage-3 image: the
+ *   ActiveArea, which for `simulateCapture` is exactly the output frame. The list is big-endian whatever the file's byte order: a
+ *   LONG opcode count, then per opcode its LONG id, the four-byte DNG version that introduced it (1.3.0.0), LONG flags and the LONG
+ *   byte count of its parameters. Every opcode is written with flag bit 0 ("optional") set, so a reader that does not support it may
+ *   skip it, and bit 1 (preview skip) clear.
+ * - FixVignetteRadial (id 3) first, when vignetting is on: parameters k0…k4, cx, cy (DOUBLE); each pixel is multiplied by
+ *   g = 1 + k0r² + k1r⁴ + k2r⁶ + k3r⁸ + k4r¹⁰, r the distance from the optical centre (cx, cy) normalized to 1 at the image's
+ *   farthest corner. It runs before the warp, so it acts at the captured (source) position, where the capture applied the falloff.
+ *   The target gain is the profile's (#584): G(ρ) = det J(ρ_i)/E(ρ), E = (1 − bρ²)² the lens's relative illumination at the
+ *   capture's f-number and det J = (1 + k1ρ_i²)(1 + 3k1ρ_i²) at the ideal radius ρ_i with ρ_i(1 + k1ρ_i²) = ρ (the lens's own k1,
+ *   whether or not distortion is corrected). G is not a polynomial in r², so k0…k4 are a near-minimax fit of g/G − 1 (Lawson's
+ *   iteratively reweighted least squares) on 2 048 radii in [0, 1]; its largest |g/G − 1| there is reported, and a fit worse than
+ *   0.1 % is refused (every catalogue lens fits within 0.07 %; GainMap, id 9, would be needed otherwise).
+ * - WarpRectilinear (id 1) then, when distortion or lateral colour is on: N = 1 plane (no lateral colour) or 3 planes (red,
+ *   green, blue; CFAPlaneColor 0 1 2), each kr0…kr3, kt0, kt1, then cx, cy (DOUBLE). For a destination pixel at normalized
+ *   offset (dx, dy) from the centre, r² = dx² + dy², the source is the centre plus (dx, dy)·(kr0 + kr1r² + kr2r⁴ + kr3r⁶) plus the
+ *   tangential terms (kt0 = kt1 = 0 here). `output.lensCorrections` reads channel c at s = q(1 + k1|q|²/R²), q = m·a_c·p (R the
+ *   half-diagonal, a_c the channel's lateral-colour scale, m the zoom-to-fill factor): so kr0 = m·a_c, kr1 = k1·(m·a_c)³·(R_DNG/R)²,
+ *   kr2 = kr3 = 0 represent it exactly (R_DNG the centre-to-corner distance of the stage-3 image; equal to R for `simulateCapture`).
+ *   The zoom-to-fill of #570 is folded into kr0, so an editor's result has the corrected JPEG's framing.
+ * - The optical centre is the image centre, cx = cy = 0.5 (0 the left or top edge, 1 the right or bottom edge).
+ *
+ * Limits: the gain is an approximation fitted to the profile (itself a labelled catalogue approximation); a reader's resampling
+ * filter, and whether it applies opcodes at all, is the reader's. Some editors apply DNG opcodes automatically with no control in
+ * the editor: the switch that is guaranteed is leaving a correction out of the DNG.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { prepareDevelopedLensCorrection } from "../output/developed-lens-corrections.js";
+/** @internal Largest accepted |g/G − 1| of the FixVignetteRadial fit. */
+export const DNG_VIGNETTE_FIT_TOLERANCE = 1e-3;
+/**
+ * @internal The OpcodeList3 bytes and the opcodes for a catalogue lens (`resolveGenericLens` at the capture's f-number, on the
+ * W × H ActiveArea of pitch `pitchMm`) and the selected corrections, at least one on (see the module notes).
+ */
+export function createDngLensCorrectionOpcodes(lens, selection, width, height, pitchMm, channels) {
+    const opcodes = [], params = [];
+    // R_DNG / R: the stage-3 image's centre-to-corner distance over the profile's half-diagonal (1 when the frame is the lens's area).
+    const scale = Math.hypot(width, height) / 2 / (lens.halfDiagonalMm / pitchMm);
+    if (selection.vignetting) {
+        const b = 1 - 2 ** (-lens.character.vignetting.cornerStops / 2), k1 = lens.character.distortion.corner;
+        const target = (r) => {
+            const rho = r * scale, e = 1 - b * rho * rho;
+            let ri = rho;
+            for (let n = 0; n < 8; n++)
+                ri -= (ri * (1 + k1 * ri * ri) - rho) / (1 + 3 * k1 * ri * ri);
+            return (1 + k1 * ri * ri) * (1 + 3 * k1 * ri * ri) / (e * e);
+        };
+        // Near-minimax fit of the relative error g/G − 1 (t = r²: rows t^j/G, j = 1…5, against 1 − 1/G) by Lawson's iteratively
+        // reweighted least squares on 2 048 radii in [0, 1] (normal equations, positive definite); of 64 iterations the one with the
+        // smallest largest error on those radii is kept.
+        const radii = Array.from({ length: 2048 }, (_, i) => { const r = i / 2047; return [r * r, target(r), 1]; });
+        let best = [0, 0, 0, 0, 0], worst = Infinity;
+        for (let iteration = 0; iteration < 64; iteration++) {
+            const a = Array.from({ length: 5 }, () => [0, 0, 0, 0, 0, 0]), k = [0, 0, 0, 0, 0];
+            for (const [t, G, w] of radii) {
+                const row = [t, t ** 2, t ** 3, t ** 4, t ** 5, G - 1].map((v) => v / G);
+                for (let j = 0; j < 5; j++)
+                    for (let m = 0; m < 6; m++)
+                        a[j][m] += w * row[j] * row[m];
+            }
+            for (let j = 0; j < 5; j++)
+                for (let i = j + 1; i < 5; i++) {
+                    const f = a[i][j] / a[j][j];
+                    for (let m = j; m < 6; m++)
+                        a[i][m] -= f * a[j][m];
+                }
+            for (let j = 4; j >= 0; j--)
+                k[j] = (a[j][5] - a[j].slice(j + 1, 5).reduce((sum, v, m) => sum + v * k[j + 1 + m], 0)) / a[j][j];
+            const errors = radii.map(([t, G]) => Math.abs((1 + t * (k[0] + t * (k[1] + t * (k[2] + t * (k[3] + t * k[4]))))) / G - 1)), max = Math.max(...errors);
+            if (max < worst) {
+                worst = max;
+                best = k;
+            }
+            radii.forEach((p, i) => { p[2] = p[2] * (errors[i] / max + 1e-9); });
+        }
+        if (!(worst <= DNG_VIGNETTE_FIT_TOLERANCE))
+            throw new InvalidConfigurationError("output.dng.lensCorrectionOpcodes: FixVignetteRadial cannot hold " + lens.name + "'s vignetting gain within 0.1 %.");
+        opcodes.push({ opcode: "FixVignetteRadial", coefficients: best, maximumRelativeFitError: worst });
+        params.push([...best, 0.5, 0.5]);
+    }
+    if (selection.distortion || selection.lateralColor) {
+        const c = prepareDevelopedLensCorrection(lens, { ...selection, vignetting: false }, width, height, pitchMm, channels);
+        const planes = (selection.lateralColor ? c.scales : [1]).map((s) => { const a = c.fill * s; return [a, c.k1 * a ** 3 * scale * scale, 0, 0, 0, 0]; });
+        opcodes.push({ opcode: "WarpRectilinear", planes, magnification: 1 / c.fill });
+        params.push([planes.length, ...planes.flat(), 0.5, 0.5]);
+    }
+    // Big-endian: the count, then per opcode its id, DNG version 1.3.0.0, flags 1 (optional), parameter bytes and parameters
+    // (all DOUBLE but WarpRectilinear's leading LONG plane count).
+    const size = (i) => params[i].length * 8 - (opcodes[i].opcode === "WarpRectilinear" ? 4 : 0);
+    const bytes = new Uint8Array(4 + params.reduce((sum, _, i) => sum + 16 + size(i), 0)), view = new DataView(bytes.buffer);
+    view.setUint32(0, opcodes.length);
+    let at = 4;
+    params.forEach((values, i) => {
+        const warp = opcodes[i].opcode === "WarpRectilinear";
+        view.setUint32(at, warp ? 1 : 3);
+        view.setUint32(at + 4, 0x01030000);
+        view.setUint32(at + 8, 1);
+        view.setUint32(at + 12, size(i));
+        at += 16;
+        values.forEach((v, j) => { if (warp && j === 0) {
+            view.setUint32(at, v);
+            at += 4;
+        }
+        else {
+            view.setFloat64(at, v);
+            at += 8;
+        } });
+    });
+    return { opcodeList3: bytes, opcodes };
+}
+//# sourceMappingURL=dng-lens-correction-opcodes.js.map

package/dist/capture/dng-lens-correction-opcodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dng-lens-correction-opcodes.js","sourceRoot":"","sources":["../../src/capture/dng-lens-correction-opcodes.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n// This product includes DNG technology under license by Adobe.\n\n/**\n * @internal #587: a catalogue lens's generic corrections (`createGenericLensCorrectionProfile`, the same arithmetic as `output.lensCorrections`)\n * written as a DNG opcode list, so a RAW editor that applies DNG opcodes corrects the DNG non-destructively; the RAW codes are never\n * changed. Written from the Adobe DNG Specification (opcode lists were added in version 1.3.0.0; the repository's writer follows\n * 1.7.1.0), chapter \"Opcode List Processing\":\n *\n * - The list goes into OpcodeList3 (tag 51022, UNDEFINED), which a reader applies to the linear, demosaiced stage-3 image: the\n *   ActiveArea, which for `simulateCapture` is exactly the output frame. The list is big-endian whatever the file's byte order: a\n *   LONG opcode count, then per opcode its LONG id, the four-byte DNG version that introduced it (1.3.0.0), LONG flags and the LONG\n *   byte count of its parameters. Every opcode is written with flag bit 0 (\"optional\") set, so a reader that does not support it may\n *   skip it, and bit 1 (preview skip) clear.\n * - FixVignetteRadial (id 3) first, when vignetting is on: parameters k0…k4, cx, cy (DOUBLE); each pixel is multiplied by\n *   g = 1 + k0r² + k1r⁴ + k2r⁶ + k3r⁸ + k4r¹⁰, r the distance from the optical centre (cx, cy) normalized to 1 at the image's\n *   farthest corner. It runs before the warp, so it acts at the captured (source) position, where the capture applied the falloff.\n *   The target gain is the profile's (#584): G(ρ) = det J(ρ_i)/E(ρ), E = (1 − bρ²)² the lens's relative illumination at the\n *   capture's f-number and det J = (1 + k1ρ_i²)(1 + 3k1ρ_i²) at the ideal radius ρ_i with ρ_i(1 + k1ρ_i²) = ρ (the lens's own k1,\n *   whether or not distortion is corrected). G is not a polynomial in r², so k0…k4 are a near-minimax fit of g/G − 1 (Lawson's\n *   iteratively reweighted least squares) on 2 048 radii in [0, 1]; its largest |g/G − 1| there is reported, and a fit worse than\n *   0.1 % is refused (every catalogue lens fits within 0.07 %; GainMap, id 9, would be needed otherwise).\n * - WarpRectilinear (id 1) then, when distortion or lateral colour is on: N = 1 plane (no lateral colour) or 3 planes (red,\n *   green, blue; CFAPlaneColor 0 1 2), each kr0…kr3, kt0, kt1, then cx, cy (DOUBLE). For a destination pixel at normalized\n *   offset (dx, dy) from the centre, r² = dx² + dy², the source is the centre plus (dx, dy)·(kr0 + kr1r² + kr2r⁴ + kr3r⁶) plus the\n *   tangential terms (kt0 = kt1 = 0 here). `output.lensCorrections` reads channel c at s = q(1 + k1|q|²/R²), q = m·a_c·p (R the\n *   half-diagonal, a_c the channel's lateral-colour scale, m the zoom-to-fill factor): so kr0 = m·a_c, kr1 = k1·(m·a_c)³·(R_DNG/R)²,\n *   kr2 = kr3 = 0 represent it exactly (R_DNG the centre-to-corner distance of the stage-3 image; equal to R for `simulateCapture`).\n *   The zoom-to-fill of #570 is folded into kr0, so an editor's result has the corrected JPEG's framing.\n * - The optical centre is the image centre, cx = cy = 0.5 (0 the left or top edge, 1 the right or bottom edge).\n *\n * Limits: the gain is an approximation fitted to the profile (itself a labelled catalogue approximation); a reader's resampling\n * filter, and whether it applies opcodes at all, is the reader's. Some editors apply DNG opcodes automatically with no control in\n * the editor: the switch that is guaranteed is leaving a correction out of the DNG.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { prepareDevelopedLensCorrection, type ChannelDispersion, type DevelopedLensCorrectionSelection } from \"../output/developed-lens-corrections.js\";\n\n/** @internal An opcode as written (application order), for the assumptions. */\nexport type DngLensCorrectionOpcode =\n  /** k0…k4 of g = 1 + k0r² + … + k4r¹⁰, and the largest |g/G − 1| on 2 048 radii in [0, 1]. */\n  | { opcode: \"FixVignetteRadial\"; coefficients: number[]; maximumRelativeFitError: number }\n  /** kr0…kr3, kt0, kt1 of one plane (all channels) or red, green, blue; the zoom-to-fill 1/m folded into kr0. */\n  | { opcode: \"WarpRectilinear\"; planes: number[][]; magnification: number };\n\n/** @internal Largest accepted |g/G − 1| of the FixVignetteRadial fit. */\nexport const DNG_VIGNETTE_FIT_TOLERANCE = 1e-3;\n\n/**\n * @internal The OpcodeList3 bytes and the opcodes for a catalogue lens (`resolveGenericLens` at the capture's f-number, on the\n * W × H ActiveArea of pitch `pitchMm`) and the selected corrections, at least one on (see the module notes).\n */\nexport function createDngLensCorrectionOpcodes(lens: Parameters<typeof prepareDevelopedLensCorrection>[0] & { name: string; character: { vignetting: { cornerStops: number } } },\n  selection: DevelopedLensCorrectionSelection, width: number, height: number, pitchMm: number, channels: ChannelDispersion): { opcodeList3: Uint8Array; opcodes: DngLensCorrectionOpcode[] } {\n  const opcodes: DngLensCorrectionOpcode[] = [], params: number[][] = [];\n  // R_DNG / R: the stage-3 image's centre-to-corner distance over the profile's half-diagonal (1 when the frame is the lens's area).\n  const scale = Math.hypot(width, height) / 2 / (lens.halfDiagonalMm / pitchMm);\n  if (selection.vignetting) {\n    const b = 1 - 2 ** (-lens.character.vignetting.cornerStops / 2), k1 = lens.character.distortion.corner;\n    const target = (r: number): number => {\n      const rho = r * scale, e = 1 - b * rho * rho;\n      let ri = rho;\n      for (let n = 0; n < 8; n++) ri -= (ri * (1 + k1 * ri * ri) - rho) / (1 + 3 * k1 * ri * ri);\n      return (1 + k1 * ri * ri) * (1 + 3 * k1 * ri * ri) / (e * e);\n    };\n    // Near-minimax fit of the relative error g/G − 1 (t = r²: rows t^j/G, j = 1…5, against 1 − 1/G) by Lawson's iteratively\n    // reweighted least squares on 2 048 radii in [0, 1] (normal equations, positive definite); of 64 iterations the one with the\n    // smallest largest error on those radii is kept.\n    const radii = Array.from({ length: 2048 }, (_, i) => { const r = i / 2047; return [r * r, target(r), 1]; });\n    let best = [0, 0, 0, 0, 0], worst = Infinity;\n    for (let iteration = 0; iteration < 64; iteration++) {\n      const a = Array.from({ length: 5 }, () => [0, 0, 0, 0, 0, 0]), k = [0, 0, 0, 0, 0];\n      for (const [t, G, w] of radii) {\n        const row = [t!, t! ** 2, t! ** 3, t! ** 4, t! ** 5, G! - 1].map((v) => v / G!);\n        for (let j = 0; j < 5; j++) for (let m = 0; m < 6; m++) a[j]![m]! += w! * row[j]! * row[m]!;\n      }\n      for (let j = 0; j < 5; j++) for (let i = j + 1; i < 5; i++) { const f = a[i]![j]! / a[j]![j]!; for (let m = j; m < 6; m++) a[i]![m]! -= f * a[j]![m]!; }\n      for (let j = 4; j >= 0; j--) k[j] = (a[j]![5]! - a[j]!.slice(j + 1, 5).reduce((sum, v, m) => sum + v * k[j + 1 + m]!, 0)) / a[j]![j]!;\n      const errors = radii.map(([t, G]) => Math.abs((1 + t! * (k[0]! + t! * (k[1]! + t! * (k[2]! + t! * (k[3]! + t! * k[4]!))))) / G! - 1)), max = Math.max(...errors);\n      if (max < worst) { worst = max; best = k; }\n      radii.forEach((p, i) => { p[2] = p[2]! * (errors[i]! / max + 1e-9); });\n    }\n    if (!(worst <= DNG_VIGNETTE_FIT_TOLERANCE)) throw new InvalidConfigurationError(\"output.dng.lensCorrectionOpcodes: FixVignetteRadial cannot hold \" + lens.name + \"'s vignetting gain within 0.1 %.\");\n    opcodes.push({ opcode: \"FixVignetteRadial\", coefficients: best, maximumRelativeFitError: worst });\n    params.push([...best, 0.5, 0.5]);\n  }\n  if (selection.distortion || selection.lateralColor) {\n    const c = prepareDevelopedLensCorrection(lens, { ...selection, vignetting: false }, width, height, pitchMm, channels);\n    const planes = (selection.lateralColor ? c.scales : [1]).map((s) => { const a = c.fill * s; return [a, c.k1 * a ** 3 * scale * scale, 0, 0, 0, 0]; });\n    opcodes.push({ opcode: \"WarpRectilinear\", planes, magnification: 1 / c.fill });\n    params.push([planes.length, ...planes.flat(), 0.5, 0.5]);\n  }\n  // Big-endian: the count, then per opcode its id, DNG version 1.3.0.0, flags 1 (optional), parameter bytes and parameters\n  // (all DOUBLE but WarpRectilinear's leading LONG plane count).\n  const size = (i: number): number => params[i]!.length * 8 - (opcodes[i]!.opcode === \"WarpRectilinear\" ? 4 : 0);\n  const bytes = new Uint8Array(4 + params.reduce((sum, _, i) => sum + 16 + size(i), 0)), view = new DataView(bytes.buffer);\n  view.setUint32(0, opcodes.length);\n  let at = 4;\n  params.forEach((values, i) => {\n    const warp = opcodes[i]!.opcode === \"WarpRectilinear\";\n    view.setUint32(at, warp ? 1 : 3); view.setUint32(at + 4, 0x01030000); view.setUint32(at + 8, 1); view.setUint32(at + 12, size(i)); at += 16;\n    values.forEach((v, j) => { if (warp && j === 0) { view.setUint32(at, v); at += 4; } else { view.setFloat64(at, v); at += 8; } });\n  });\n  return { opcodeList3: bytes, opcodes };\n}\n"]}

package/dist/capture/exposure-build-up-stage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal (#534): the sensor-stage hook of one render of an exposure build-up (`simulateExposureBuildUp`). After a site's
+ * ordinary photo and dark draws, `split` gets the render's expected means and those draws, and sets the counts the readout
+ * uses (`photo`, `dark`); `read` names the readout's read-noise stream. The build-up's own logic (binomial splitting, the
+ * per-site chain) lives in facade/exposure-build-up.ts, so captures without a build-up carry only this registry.
+ */
+export interface ExposureBuildUpStage {
+    /** Sets `photo` and `dark` for the absolute native site `index` from this render's expected means and ordinary draws. */
+    split(index: number, photoMean: number, darkMean: number, photo: number, dark: number): void;
+    photo: number;
+    dark: number;
+    /** The read-noise stream ID of the readout (`deriveNativeSiteStreamSeedUint32`). */
+    read: number;
+}
+/** The running build-up renders' stages, by their native RAW input (`NativeRawInput`, the object the capture facade builds). */
+export declare const EXPOSURE_BUILD_UP_STAGES: WeakMap<object, ExposureBuildUpStage>;

package/dist/capture/exposure-build-up-stage.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+/** The running build-up renders' stages, by their native RAW input (`NativeRawInput`, the object the capture facade builds). */
+export const EXPOSURE_BUILD_UP_STAGES = new WeakMap();
+//# sourceMappingURL=exposure-build-up-stage.js.map

package/dist/capture/exposure-build-up-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure-build-up-stage.js","sourceRoot":"","sources":["../../src/capture/exposure-build-up-stage.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAkBtC,gIAAgI;AAChI,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,OAAO,EAAgC,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (#534): the sensor-stage hook of one render of an exposure build-up (`simulateExposureBuildUp`). After a site's\n * ordinary photo and dark draws, `split` gets the render's expected means and those draws, and sets the counts the readout\n * uses (`photo`, `dark`); `read` names the readout's read-noise stream. The build-up's own logic (binomial splitting, the\n * per-site chain) lives in facade/exposure-build-up.ts, so captures without a build-up carry only this registry.\n */\n\nexport interface ExposureBuildUpStage {\n  /** Sets `photo` and `dark` for the absolute native site `index` from this render's expected means and ordinary draws. */\n  split(index: number, photoMean: number, darkMean: number, photo: number, dark: number): void;\n  photo: number;\n  dark: number;\n  /** The read-noise stream ID of the readout (`deriveNativeSiteStreamSeedUint32`). */\n  read: number;\n}\n\n/** The running build-up renders' stages, by their native RAW input (`NativeRawInput`, the object the capture facade builds). */\nexport const EXPOSURE_BUILD_UP_STAGES = new WeakMap<object, ExposureBuildUpStage>();\n"]}

package/dist/capture/native-environment-lean.d.ts

@@ -41,6 +41,7 @@ import { parseFocusPlane } from "../optics/focus-state.js";
 import { prepareCaptureExposureWindowSampler } from "../sensor/exposure-window.js";
 import { calculateNativeRawSite, type NativeRawProducerFrameContext, type SensorRawProducerSiteInput } from "./sensor-raw-producer.js";
 import type { NativeRawLeanOutput, NativeRawLeanSensorHook } from "./native-raw.js";
+import type { ExposureBuildUpStage } from "./exposure-build-up-stage.js";
 type Site = SimulateEnvironmentSensorRawFrameInput["sites"][number];
 type Env = Site["environment"];
 type FullPlan = ReturnType<typeof planEnvironmentSensorPhotoSignal>;
@@ -230,7 +231,7 @@ export interface NativeSiteReadout {
  * its codes and its flags bit for bit. Its `compute` then gives `calculateNativeRawSite`'s outputs for any site of the same
  * readout inputs (same CFA channel, dark current, capacity, readout regime and fixed-pattern profile).
  */
-export declare function createVerifiedNativeSiteReadout(parsed: SensorRawProducerSiteInput, result: ReturnType<typeof calculateNativeRawSite>, whiteCode: number, photo: SensorEqeTemporalPhotoSignal, x: number, y: number, index: number, seed: number): NativeSiteReadout | undefined;
+export declare function createVerifiedNativeSiteReadout(parsed: SensorRawProducerSiteInput, result: ReturnType<typeof calculateNativeRawSite>, whiteCode: number, photo: SensorEqeTemporalPhotoSignal, x: number, y: number, index: number, seed: number, b?: ExposureBuildUpStage): NativeSiteReadout | undefined;
 /**
  * Lean sensor stage for createNativeEnvironmentRawTask.
  *

package/dist/capture/native-environment-lean.js

@@ -24,10 +24,10 @@ import { calculateSiteEffectiveSaturationCode } from "./raw-white-level.js";
 import { adcTransfer, resolveSensorReadoutRegime, samplePoisson } from "../sensor/raw-readout.js";
 import { createResettableUniformStream, deriveNativeSiteStreamSeedUint32, sampleDeterministicStandardNormal, NATIVE_SITE_CHARGE_STREAM_ID, NATIVE_SITE_READ_NOISE_STREAM_ID } from "../sensor/stochastic-seed.js";
 import { evaluateParsedFixedPatternSite } from "../sensor/fixed-pattern-noise.js";
+import { approximatelyEqual } from "../core/shared-helpers.js";
 /** Most distinct templates kept for one capture event. Any further distinct sites just run the full path. */
 const MAXIMUM_TEMPLATES = 64;
 const SQUARE_MICROMETERS_TO_SQUARE_METERS = 1e-12;
-const REDUCTION_TOLERANCE = 1e-10;
 /** Disables the lean executor process-wide (internal; tests compare both paths). */
 let leanDisabled = false;
 /** Internal counters of lean work (tests assert the lean path actually runs). Not exported from the package. */
@@ -882,10 +882,6 @@ export function createNativeEnvironmentLeanExecutor(frame, access) {
         }
     };
 }
-function approximatelyEqual(actual, expected) {
-    const scale = Math.max(1, Math.abs(actual), Math.abs(expected));
-    return Math.abs(actual - expected) <= REDUCTION_TOLERANCE * scale;
-}
 /** Photo-signal fields that vary per site; every other field is template-level. */
 const PHOTO_SITE_FIELDS = new Set(["temporalIntegrationId", "site", "startOffsetSecondsFromOpeningReference",
     "endOffsetSecondsFromOpeningReference", "localExposureDurationSeconds", "expectedIncidentPhotonCount", "expectedGeneratedElectronCount", "temporalSamples"]);
@@ -969,58 +965,21 @@ function sensorMatches(site, photo, x, y, t, memo) {
     return sameRecordExcept(photo, t.photo, PHOTO_SITE_FIELDS, memo) && siteSlot(photo.site, x, y) &&
         photo.temporalSamples.length === t.photo.temporalSamples.length;
 }
-/** The sensor stage of calculateNativeRawSite, in the same operation order. Returns undefined when one of its checks would throw. */
 /**
- * #418: the charge and read-noise streams of the site leanSensorSite is computing, reseeded for each site. leanSensorSite is
+ * #418: the charge and read-noise streams of the site flatSensorSite is computing, reseeded for each site. flatSensorSite is
  * synchronous and never re-entered, so one pair serves every call; reseeding sets exactly the state a new
  * createDeterministicUniformStream would start from, so every draw is unchanged.
  */
 const chargeStream = createResettableUniformStream(), readNoiseStream = createResettableUniformStream();
-function leanSensorSite(t, h, index, seed) {
-    const ratio = h.total / t.capacity, headroom = t.capacity - h.total;
-    if (!Number.isFinite(ratio) || !Number.isFinite(headroom))
-        return undefined;
-    const pattern = t.pattern === undefined ? null : evaluateParsedFixedPatternSite(t.pattern, { x: h.x, y: h.y });
-    const photoE = h.photo.expectedGeneratedElectronCount;
-    const photoMean = pattern === null ? photoE : photoE * pattern.photoResponseGainFactor;
-    const darkMean = pattern === null ? h.darkE : h.darkE * pattern.darkCurrentFactor;
-    if (!Number.isFinite(photoMean) || photoMean < 0 || !Number.isFinite(darkMean) || darkMean < 0)
-        return undefined;
-    const random = chargeStream;
-    random.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_CHARGE_STREAM_ID));
-    const photoRealized = samplePoisson(photoMean, random), darkRealized = samplePoisson(darkMean, random);
-    const realized = photoRealized + darkRealized + 0;
-    if (!Number.isFinite(realized) || realized < 0)
-        return undefined;
-    const readRandom = readNoiseStream;
-    readRandom.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_READ_NOISE_STREAM_ID));
-    const regime = t.readout.regime, capacity = t.capacity;
-    const afterPhysical = Math.min(realized, capacity), physicalSaturation = afterPhysical < realized;
-    // The components' draws and their sum in one loop: the same draws, added to 0 in the same order as before (#418).
-    const components = regime.readNoiseComponents;
-    let totalReadNoise = 0;
-    for (let k = 0; k < components.length; k++) {
-        const rms = components[k].rmsElectrons.value;
-        totalReadNoise = totalReadNoise + (rms === 0 ? 0 : sampleDeterministicStandardNormal(readRandom) * rms);
-    }
-    const afterReadNoise = afterPhysical + totalReadNoise + (pattern === null ? 0 : pattern.readoutOffsetElectrons);
-    const threshold = regime.preAdcSaturationElectronEquivalent.value;
-    const afterPreAdc = Math.min(afterReadNoise, threshold), preAdcSaturation = afterReadNoise > threshold;
-    const quantized = adcTransfer(regime, t.readout.adcMaximumCode, afterPreAdc).quantized;
-    const digitalSaturationCode = regime.adc.digitalSaturationCode;
-    return { rawCode: Math.max(0, Math.min(quantized, digitalSaturationCode)), blackLevelCode: regime.adc.blackLevelCode, digitalSaturationCode,
-        flags: Number(physicalSaturation) | Number(preAdcSaturation) << 1 | Number(quantized >= digitalSaturationCode) << 2,
-        whiteCode: t.whiteCode, photoRealized, darkRealized };
-}
-function flatSensorStage(t) {
+function flatSensorStage(t, b) {
     const regime = t.readout.regime;
     return { darkRate: t.darkRate, capacity: t.capacity, pattern: t.pattern, whiteCode: t.whiteCode, regime, adcMaximumCode: t.readout.adcMaximumCode,
         inlDefined: regime.adc.integralNonLinearity !== undefined, gain: regime.systemConversionGainElectronsPerCode.value, black: regime.adc.blackLevelCode,
         digitalGain: regime.adc.digitalGain, digitalSaturationCode: regime.adc.digitalSaturationCode, threshold: regime.preAdcSaturationElectronEquivalent.value,
         rms: Float64Array.from(regime.readNoiseComponents, (component) => component.rmsElectrons.value), darkMean: NaN, darkThreshold: NaN,
-        out: { rawCode: 0, blackLevelCode: 0, digitalSaturationCode: 0, flags: 0, whiteCode: 0 } };
+        out: { rawCode: 0, blackLevelCode: 0, digitalSaturationCode: 0, flags: 0, whiteCode: 0, photoRealized: 0, darkRealized: 0 }, b };
 }
-/** Writes the site's outputs into `f.out`; false where leanSensorSite returns undefined. */
+/** Writes the site's outputs into `f.out`; false where a check of calculateNativeRawSite would throw. */
 function flatSensorSite(f, photoE, darkE, total, x, y, index, seed) {
     const ratio = total / f.capacity, headroom = f.capacity - total;
     if (!Number.isFinite(ratio) || !Number.isFinite(headroom))
@@ -1032,8 +991,7 @@ function flatSensorSite(f, photoE, darkE, total, x, y, index, seed) {
         return false;
     const random = chargeStream;
     random.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_CHARGE_STREAM_ID));
-    const photoRealized = samplePoisson(photoMean, random);
-    let darkRealized;
+    let photoRealized = samplePoisson(photoMean, random), darkRealized;
     if (darkMean > 0 && darkMean < 30) {
         // samplePoisson's branch for 0 < mean < 30 (Knuth's product of uniforms) with its threshold Math.exp(−mean) kept while the
         // mean repeats: the same draws from the same stream. (createPoissonSampler would also do this, but it brings the
@@ -1052,11 +1010,17 @@ function flatSensorSite(f, photoE, darkE, total, x, y, index, seed) {
     }
     else
         darkRealized = samplePoisson(darkMean, random);
+    const b = f.b;
+    if (b) {
+        b.split(index, photoMean, darkMean, photoRealized, darkRealized);
+        photoRealized = b.photo;
+        darkRealized = b.dark;
+    }
     const realized = photoRealized + darkRealized + 0;
     if (!Number.isFinite(realized) || realized < 0)
         return false;
     const readRandom = readNoiseStream;
-    readRandom.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_READ_NOISE_STREAM_ID));
+    readRandom.reset(deriveNativeSiteStreamSeedUint32(seed, index, b ? b.read : NATIVE_SITE_READ_NOISE_STREAM_ID));
     const capacity = f.capacity;
     const afterPhysical = Math.min(realized, capacity), physicalSaturation = afterPhysical < realized;
     const rmsAll = f.rms;
@@ -1088,6 +1052,8 @@ function flatSensorSite(f, photoE, darkE, total, x, y, index, seed) {
     out.digitalSaturationCode = digitalSaturationCode;
     out.flags = Number(physicalSaturation) | Number(preAdcSaturation) << 1 | Number(quantized >= digitalSaturationCode) << 2;
     out.whiteCode = f.whiteCode;
+    out.photoRealized = photoRealized;
+    out.darkRealized = darkRealized;
     return true;
 }
 /** The Kahan (compensated) total that composeSensorAccumulatedCharge computes, for photo and dark charge only. */
@@ -1100,28 +1066,32 @@ function chargeTotal(photoE, darkE) {
     }
     return sum;
 }
+/**
+ * True when the flat stage `f` reproduces the fully computed site `result` bit for bit: its dark and total charge, both charge
+ * realizations, its codes and its flags.
+ */
+function reproducesSite(f, parsed, result, photo, x, y, index, seed) {
+    const darkE = f.darkRate * photo.localExposureDurationSeconds, total = chargeTotal(photo.expectedGeneratedElectronCount, darkE);
+    const r = result.readout.value, realization = result.realization.value, out = f.out;
+    return flatSensorSite(f, photo.expectedGeneratedElectronCount, darkE, total, x, y, index, seed) && Object.is(darkE, parsed.charge.darkCharge.expectedDarkElectronCount) &&
+        Object.is(total, result.accumulatedCharge.value.totalExpectedStoredElectronCount) &&
+        Object.is(out.photoRealized, realization.photoRealizedElectronCount) && Object.is(out.darkRealized, realization.darkRealizedElectronCount) &&
+        realization.additionalComponents.length === 0 && out.rawCode === r.rawCode && out.blackLevelCode === r.blackLevelCode && out.digitalSaturationCode === r.digitalSaturationCode &&
+        out.flags === (Number(r.physicalScalarSaturationApplied) | Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2);
+}
 /**
  * #394: a sensor template from one fully parsed and computed site (`calculateNativeRawSite`), as the lean sensor stage builds
  * its templates; undefined unless the lean arithmetic reproduces that site's dark and total charge, both charge realizations,
  * its codes and its flags bit for bit. Its `compute` then gives `calculateNativeRawSite`'s outputs for any site of the same
  * readout inputs (same CFA channel, dark current, capacity, readout regime and fixed-pattern profile).
  */
-export function createVerifiedNativeSiteReadout(parsed, result, whiteCode, photo, x, y, index, seed) {
+export function createVerifiedNativeSiteReadout(parsed, result, whiteCode, photo, x, y, index, seed, b) {
     try {
         const readout = resolveSensorReadoutRegime({ profile: parsed.readoutProfile, regimeId: parsed.regimeId });
         const t = { darkRate: parsed.charge.darkCharge.darkCurrentElectronsPerSecond,
             capacity: result.capacity.value.physicalChargeCapacityElectrons, readout, pattern: parsed.fixedPatternNoise, whiteCode };
-        const darkE = t.darkRate * photo.localExposureDurationSeconds, total = chargeTotal(photo.expectedGeneratedElectronCount, darkE);
-        const r = result.readout.value, realization = result.realization.value, out = leanSensorSite(t, { photo, darkE, total, x, y }, index, seed);
-        if (!out || !Object.is(darkE, parsed.charge.darkCharge.expectedDarkElectronCount) || !Object.is(total, result.accumulatedCharge.value.totalExpectedStoredElectronCount) ||
-            !Object.is(out.photoRealized, realization.photoRealizedElectronCount) || !Object.is(out.darkRealized, realization.darkRealizedElectronCount) ||
-            realization.additionalComponents.length !== 0 || out.rawCode !== r.rawCode || out.blackLevelCode !== r.blackLevelCode || out.digitalSaturationCode !== r.digitalSaturationCode ||
-            out.flags !== (Number(r.physicalScalarSaturationApplied) | Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2))
-            return undefined;
-        // #449: the flat stage must reproduce the verification site too.
-        const flat = flatSensorStage(t), fo = flat.out;
-        if (!flatSensorSite(flat, photo.expectedGeneratedElectronCount, darkE, total, x, y, index, seed) || fo.rawCode !== out.rawCode || fo.blackLevelCode !== out.blackLevelCode ||
-            fo.digitalSaturationCode !== out.digitalSaturationCode || fo.flags !== out.flags || fo.whiteCode !== out.whiteCode)
+        const flat = flatSensorStage(t, b), fo = flat.out;
+        if (!reproducesSite(flat, parsed, result, photo, x, y, index, seed))
             return undefined;
         return {
             compute(photoE, duration, sx, sy, siteIndex, siteSeed) {
@@ -1193,20 +1163,21 @@ export function createNativeEnvironmentSensorLean(frame, producerFrame, nativeWi
             claim(site) {
                 return typeof site === "object" && site !== null && handles.has(site) ? site : undefined;
             },
-            compute(handle, index, seed, timing) {
-                const h = handles.get(handle), out = leanSensorSite(h.template, h, index, seed);
-                if (out)
+            compute(handle, index, seed, timing, b) {
+                // The template's flat stage (made in observe(), with the same build-up stage); the caller copies the outputs at once.
+                const h = handles.get(handle), f = h.template.flat;
+                if (flatSensorSite(f, h.photo.expectedGeneratedElectronCount, h.darkE, h.total, h.x, h.y, index, seed)) {
                     nativeEnvironmentLeanStatistics.sensorSites++;
-                if (out)
-                    return { rawCode: out.rawCode, blackLevelCode: out.blackLevelCode, digitalSaturationCode: out.digitalSaturationCode, flags: out.flags, whiteCode: out.whiteCode };
+                    return f.out;
+                }
                 // A compute-phase check failed: the full path computes (and throws) exactly as it would have.
                 const parsed = parseNativeRawProducerSite(composeNativeEnvironmentSensorSite(h.site, h.photo), index, producerFrame, timing);
-                const r = calculateNativeRawSite(parsed, seed, index).readout.value;
+                const r = calculateNativeRawSite(parsed, seed, index, b).readout.value;
                 return { rawCode: r.rawCode, blackLevelCode: r.blackLevelCode, digitalSaturationCode: r.digitalSaturationCode,
                     flags: Number(r.physicalScalarSaturationApplied) | Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2,
                     whiteCode: calculateSiteEffectiveSaturationCode(r, parsed.readoutProfile, parsed.regimeId) };
             },
-            observe(index, parsed, result, whiteCode, seed) {
+            observe(index, parsed, result, whiteCode, seed, b) {
                 const entry = pending.get(index);
                 pending.delete(index);
                 if (!entry || templates.length >= MAXIMUM_TEMPLATES)
@@ -1219,18 +1190,11 @@ export function createNativeEnvironmentSensorLean(frame, producerFrame, nativeWi
                     const t = { site, photo, phase, x, y, verified: false, darkRate: parsed.charge.darkCharge.darkCurrentElectronsPerSecond,
                         capacity: result.capacity.value.physicalChargeCapacityElectrons, readout, pattern: parsed.fixedPatternNoise, whiteCode };
                     templates.push(t);
-                    // Self-check: the template matches itself and the lean arithmetic reproduces its full computation bit for bit.
+                    // Self-check: the template matches itself and its flat stage reproduces its full computation bit for bit.
                     if (!sensorMatches(site, photo, x, y, t, new WeakMap()))
                         return;
-                    const darkE = t.darkRate * photo.localExposureDurationSeconds, total = chargeTotal(photo.expectedGeneratedElectronCount, darkE);
-                    const r = result.readout.value, realization = result.realization.value;
-                    const out = leanSensorSite(t, { photo, darkE, total, x, y }, index, seed);
-                    if (!out || !Object.is(darkE, parsed.charge.darkCharge.expectedDarkElectronCount) ||
-                        !Object.is(total, result.accumulatedCharge.value.totalExpectedStoredElectronCount) ||
-                        !Object.is(out.photoRealized, realization.photoRealizedElectronCount) || !Object.is(out.darkRealized, realization.darkRealizedElectronCount) ||
-                        realization.additionalComponents.length !== 0 || out.rawCode !== r.rawCode || out.blackLevelCode !== r.blackLevelCode ||
-                        out.digitalSaturationCode !== r.digitalSaturationCode || out.flags !== (Number(r.physicalScalarSaturationApplied) |
-                        Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2))
+                    t.flat = flatSensorStage(t, b);
+                    if (!reproducesSite(t.flat, parsed, result, photo, x, y, index, seed))
                         return;
                     t.verified = true;
                 }