@photivra/engine 2.21.0 → 2.22.0

package/CHANGELOG.md

@@ -1,6 +1,123 @@
 # Changelog
 
-## 2.21.0 — unreleased (prepared November 10, 2026)
+## 2.22.0 — unreleased (prepared November 11, 2026)
+
+A minor release: phone DNG import with JPEG XL and lossy JPEG raw data, the DNG stage image and opcodes (#598, #600) and the channel-response helper (#591); native-photosite sensor figures (#595), read noise per photosite on the tiers (#599), mixed lighting over an image-plane print (#597), sample counts that follow the light and the output (#590) and the catalogue's fast grid (#603); the display view's luminance tone curves, highlight reconstruction and desaturation on the CPU and GPU (#593, #601, #602); the removal of the display view's AHD low-signal correction; Content Credentials writers (#165, engine half); and the full-quality and opt-in code loaded on demand (#594). See the [2.22.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_22_0.md).
+
+- **New:** `importDngRawImage`, `parseLossyJpeg`, `createJxlOxideDngDecoder`, `parseDngOpcodeList`, `applyDngOpcodes`, `developDngStageImage`, `parseDngProfileGainTableMap`, `parseDngRgbTables`, `applyDngProfileGainTableMap`, `applyDngRgbTables` (#598, #600); `calculateCameraChannelResponse` (#591); `result.sensor.native` (#595); `output.gamutHandling: "desaturate-to-luminance"` (#601) and `output.highlightMode: "reconstruct-neighbors"` (#602); the luminance tone curves and `highlightMode: "reconstruct"` in the display view (#593); `bindC2paManifestStore`, `calculateC2paDataHash`, `setC2paManifestStore`, `parseC2paManifestStore` (#165); `prepareQualityPaths()` (#594).
+- **Changed (see "Default changes"):** the tiers' read noise is per photosite (#599); the default spectral step under a spiky light on exact requests (#590); the catalogue's fast grid (#603); mixed lighting over a print is rendered (#597); the display view's AHD has no low-signal correction; two `raw.expectedSignal` method names; the GPU Quality self-check runs at the first Quality render; the full-quality and opt-in code loads on demand (#594).
+- **Root exports:** 50 new, 1,931 → 1,981 (runtime exports 654 → 672): 29 from #598 and #600 (11 runtime), 3 from #591 (1 runtime), 2 from #595 (types), 15 from #165 (6 runtime), 1 from #594 (runtime). Nothing is removed; the AHD correction-state API is deprecated (no-ops until 3.0.0).
+- **Why minor:** new root exports and options; every default change below keeps the old behavior one option away or is a model correction or a removal the owner decided, with its deprecated API kept.
+
+### Default changes (migration)
+
+| What changed | Before (2.21.0) | Now (2.22.0) | Keep the old behavior |
+| --- | --- | --- | --- |
+| Generic tiers' (and caller presets') read noise above 6 µm, and `sensor.readNoise` on a tier (#599; owner decision 2026-11-11) | once per rendered site, whatever the pitch; `sensor.readNoise` was the site's value | the read noise of one physical photosite (as a datasheet gives it, as for a sensor profile, #554): a site that sums N = pitch²/36 µm² photosites takes it ×√N; `native.readNoiseElectrons` reports it as given; at 6 µm and below unchanged | set `sensor.readNoise` to the 2.21.0 site value divided by √N = pitch / 6 µm |
+| Default spectral step under a spiky light (#590) | 20 nm | 5 nm on exact requests (DNG, JPEG, PNG, the ideal reference, `fast: false`) when R(20) = 20²·κ/24 > 0.01: the four #557 representative sources (fluorescent 0.84, LEDs 0.017–0.038); fast requests keep 20 nm with the assumption `sensor.spectralSpikiness` and `diagnostics.fast.applied` reporting it; Planck, CIE A and other smooth lights unchanged | `sensor.spectralStepNanometers: 20` |
+| Catalogue field grid on fast requests (#603) | at least 10 cells per field interval | at least 4 (2.20.0's grid) on fast requests (on-screen sRGB captures), except the measured lenses of `CATALOGUE_FAST_GRID_FULL_ON_SCREEN` (the PV 15 2.8 Fisheye Pro), which keep 10; exact requests keep 10 | `fast: false` with `lens.catalogue: { kind, fast: true }` |
+| Mixed lighting over an image-plane print (#597) | refused | rendered: every site integrates the lit radiance per node on the CPU; the GPU display view lights each lattice point in the print's Quality passes (Speed requests too) | — (a refusal lifted) |
+| Display view with `output.demosaic: "ahd"` (owner decision 2026-11-11) | a low-signal correction from precomputed values on a grid of the three channel signal levels | no correction on any path; `view.demosaic` labels the remaining bias an approximation with measured numbers (largest: about 4 red codes at 1.4 µm, ISO 6400) | no option (the correction-state API is kept as checked no-ops until 3.0.0) |
+| `raw.expectedSignal` method names (labels only) | `tabulated-expected-electrons`, `tabulated-expected-electrons-catalogue-psf-field-grid` | `per-site-integrated-electrons`, `per-site-integrated-electrons-catalogue-psf-field-grid` (what the paths have done since 2.21.0); samples and RAW codes unchanged | match the new names |
+| GPU Quality self-check (#594; owner decision 2026-11-10) | before a view's first GPU render | before its first render that takes the Quality passes (a Speed-only view lists only the Speed case) | no option (diagnostics timing; results unchanged) |
+| Full-quality and opt-in code (#594) | in a bundle's first load | loaded on demand, once, by the first request that uses it (a bundler that splits dynamic imports puts it in its own chunks); a request whose code cannot load fails with `ImageKernelExecutionError` reason `quality-code-unavailable` (the GPU falls back to the CPU) | `await prepareQualityPaths()` at start-up; results are unchanged either way |
+
+### Integration (this release)
+
+- **Parts:** six part branches merged `--no-ff` (docs/RELEASE_2_22_0.md, "Scope"); every part's behavior is kept. The AHD correction's removal and #593's coupled rendering met in the display view's CPU and GPU code: the coupled steps keep their constants after the aux table, and the pixel pass's bindings are the five without the correction's state table, bitmap and threshold.
+- **Cross-part fixes (tests and inputs, no result change):** the DNG import helpers reject malformed input with domain errors (no raw `TypeError`); `import`, `apply` and `develop` are documented verb families (docs/API_STYLE.md); a bound DNG's import names the C2PA store tag as present and not applied, now checked; the GPU renderer's `supports()` keeps refusing unknown tone curves and accepts the two luminance curves; hash locks re-recorded only where two parts changed the same output, each checked against the part that changed its bytes. #597's image-plane light shader declared a local named `common`, a WGSL reserved word that Chrome 153 refuses on hardware adapters; renamed (results unchanged), and a test now rejects reserved words in shipped WGSL.
+- **The GPU coupled steps on SwiftShader (#593, #601):** the Speed kernel and the Quality pixel pass with the coupled steps did not compile on SwiftShader (the GPU process ended after about 44 s; the same on the part alone). Bisected to the colour-matrix lookups (`m_of`, a `switch`) inside the luminance curve's nested loops; those loops now read the matrix rows from one local array (the same values), and the kernels compile in about 2 s. Every coupled case passes on SwiftShader, the hardware adapter and the float32 emulation.
+- **CI capacity (owner decisions):** coverage runs as eight shards in `ci.yml` and `publish.yml` (six in 2.21.0; the coverage gate still merges every shard and enforces the thresholds on the whole suite), and the SwiftShader WebGPU suite as two parallel jobs, `webgpu conformance (SwiftShader, 1/2)` and `(2/2)` (`test/webgpu/display-view-quality.webgpu.ts`, split from `display-view.webgpu.ts`, runs in part 2). The slowest test files are split with the same tests: the Quality cases after the charts into `test/display-view-quality-gpu-cases.test.ts`, the coupled `reconstruct` case into `test/display-view-coupled-gpu-reconstruct.test.ts`, and the extra defocus cases into `test/display-view-defocus-gpu-extra.test.ts`. No job time limit was raised and no test was removed; `test/shard-weights.json` comes from this pull request's CI times.
+- **#594 CPU split:** see "#594 On-demand Quality code" below.
+
+### #598, #600, #591 Phone DNG import and the channel-response helper
+
+- **Phone RAW files (#598).** `parseDngRawImage` reads 8-bit lossy JPEG raw data (Compression 34892) with the engine's own sequential-DCT decoder (`parseLossyJpeg`, ITU-T T.81), and the new `importDngRawImage` also reads JPEG XL raw data (52546) through a caller-supplied decoder: `createJxlOxideDngDecoder` adapts the prebuilt jxl-oxide WebAssembly package, whose 16-bit PNG output is read with the platform's `DecompressionStream`. Lossless 8–16-bit tiles round-trip bit-exactly (synthetic fixtures). Results carry `lossySource`, the opcode lists, ForwardMatrix1/2, BaselineExposure, the profile gain table map, RGBTables, decoded semantic masks and an `assumptions` list naming every rendering tag that is present and not applied; no phone tag fails an import. Row/ColumnInterleaveFactor are undone (order inferred from the DNG SDK, reported). New `maximumBytes` memory pre-check (default 1 GiB) and `size: "half"` LinearRaw preview; the 64 MP default stays. Schema 1.1.0. Verification against the owner's phone files is pending.
+- **DNG stage image and opcodes (#598, #600).** `developDngStageImage` applies OpcodeList1, linearization, black and white levels and OpcodeList2/3 (LinearRaw); `parseDngOpcodeList` and `applyDngOpcodes` apply MapTable, MapPolynomial, GainMap, the per-row and per-column opcodes, FixVignetteRadial, WarpRectilinear (cubic convolution at full quality, bilinear with `fast`: new registry entry `dngImport.warpRectilinear`; fast by default, full quality when `format` is an export) and FixBadPixelsConstant/List; WarpFisheye, TrimBounds and WarpRectilinear2 are reported.
+- **Profile gain table map and RGBTables (#598).** `applyDngProfileGainTableMap` and `applyDngRgbTables` apply ProfileGainTableMap(2) and masked RGBTables (weighted sum or sequential) at their places in a development.
+- **Channel response helper (#591).** `calculateCameraChannelResponse({ sensorProfile?, peakQuantumEfficiency?, spectralStepNanometers?, illuminant? })` returns the capture's own channel response (electrons per joule at its spectral nodes) and, with an illuminant, the `channelDispersion` for `calculateLateralColorFringe`; full quality (5 nm) by default; agrees with a capture's reported dispersion to 1e-9. Not part of the capture worker.
+- Dev dependency jxl-oxide-wasm 0.12.6 (MIT OR Apache-2.0; chosen licence Apache-2.0) for tests; the licence check accepts SPDX `OR` expressions with an allowed choice. THIRD_PARTY.md has a JPEG XL note.
+
+### #595, #599, #597, #590, #603 Sensor figures, read noise, mixed light over prints, sample counts
+
+- **#595 New: `result.sensor.native`**, the sensor figures of one native photosite (a tier's declared 6 µm reference, a sensor profile's own pitch) beside the as-rendered ones: full well, read noise, engineering dynamic range (and per ISO), `photositesPerSite`, the mid-gray figure on exact requests, the EMVA 1288 Release 4.0 dynamic range (§2.7, Eq. 26–28: μ_e.min = √(σ_d² + σ_q² + 1/4) + 1/2, in stops and dB, with the saturation capacity per µm²), and `normalized8Megapixel`, a convention (not EMVA): DR + ½·log₂(frame photosites / 8 000 000). New root types `SimulateCaptureNativeSensorReport` and `SimulateCaptureMidGreyFigure`. Model figures, exact arithmetic. Professional tier, ISO 100/800/6400: native 14.67/12.72/9.73 stops engineering, 14.36/12.09/9.10 EMVA, at every pitch.
+- **#599 Changed:** the tiers' as-rendered read noise scales by √N above 6 µm ("Default changes"). Rendered dynamic range at 46.9 µm, ISO 100/800/6400: 15.70/15.69/15.18 → 15.66/15.20/12.69 stops (now the binned value N·S₀ / √(N·σ_read² + σ_q,N²)); 187.5 µm: 15.70 → 15.70/15.66/14.54. The mid-gray SNR changes only where read noise matters (46.9 µm, ISO 100: 688.6). Tests: `test/sensor-native-report.test.ts` (new; a dark-frame photon-transfer check at 60 µm).
+- **#597 Mixed lighting over a print.** The 2.21.0 refusal is lifted. **CPU** (capture, display view, ideal reference, moving subject, exports): the print's reflectance spectrum at each point times the blended irradiance, per spectral node, integrated per site at use; no per-pixel signal is cached under a blend (owner rule), only the pixels' reflectance spectra (by row, the same values). Measured (320 × 240 photo on a 384 × 256 DNG, 2 × 2 box): one light 73 ms; a two-source gradient 760–780 ms, a point source 590–625 ms (about 1,240 and 1,070 ms without the spectra cache). **GPU** (owner decision): the print's Quality passes take a light table (the blend's geometry and stops, the regions, the point sources, and each light's spectrum at the nodes; no channel value) and pass 1 lights each lattice point: the blend in double-float32, weights rounded once, hard edges and region edges flagged, point sources' h/d³ as bounded values, flagged when the computed bound exceeds 39·E; the site-sum bound grows by 40·E. Speed requests take these passes too (a print under a blend has no per-pixel signals). Registered as `illumination/image-plane-gpu` (fast: `gpu: "auto"`, float32; exact: the CPU reference). The self-check adds a lit case. Emulation: every case inside its bounds, samples within one code, ΔE2000 ≤ 1.9e-5, no flags on the gradient, radial-with-hard-edge and regions-plus-point cases; a regions edge exactly on the lattice is flagged (40 points) or resolved on the host (140). Charts under a blend keep the CPU. Tests: `test/image-plane-mixed-lighting.test.ts` (new), `test/display-view-image-gpu.test.ts`, `test/fast-methods-registry.test.ts`. Not measured on a hardware adapter.
+- **#603 Catalogue fast grid.** `CATALOGUE_FAST_GRID_SPEED_SUBDIVISIONS` (4) on fast requests, `CATALOGUE_FAST_GRID_MINIMUM_SUBDIVISIONS` (10) on exact ones, resolved from the request's `fast`; registered as `lens.catalogue/field-grid-cells`, reported as `minimumSubdivisions` in `fast.lens.catalogue`. Measurements (frame time, fallbacks and lateral color for both grids) in docs/LENS_CATALOGUE.md: lateral color 96–101 % of the model with either grid. Tests: `test/simulate-capture-lens-catalogue-fast.test.ts`.
+- **#590 Sample counts follow the output.** New `src/color/spectral-spikiness.ts`: κ = Σ|Δ²S| / ΣS on a 1 nm grid and R(h) = h²·κ/24 (the composite midpoint rule's error term, DLMF §3.5(i), normalized; the 0.01 threshold is a design choice). Measured κ reproduces #590's table (fluorescent R(20) 0.835; LEDs 0.0384, 0.0306, 0.0167; CIE A, Planck 2700 and 6500 K ≤ 3.0e-4). The default step is resolved after the format and the request's `fast` (the parse order changed: `fast` is now resolved before the sensor options; the light is read early for the measure). Registered as `sensor.spectralStepNanometers`, which joins `SIMULATE_CAPTURE_FAST_OPTIONS` and `SIMULATE_CAPTURE_COST_OPTIONS` (owner decision 2026-11-11): under a spiky light with the default step `diagnostics.fast.applied` reports it (true on fast requests, with `assurance: "approximation-with-a-priori-bound"`; false on exact ones), so a DNG join refuses fast parts; otherwise no key is added. White under the fluorescent source, exact: 5 nm within 0.34 % of 1 nm per channel; 20 nm 70 % off in one. Cost of 5 nm against 20 nm on a 384 × 256 DNG (tabulated path): 44 against 40 ms. **Measured, not changed (owner: decide from the numbers):** `sensor.pixelAperture.samplesPerAxis` (default 4) against 16, noise-free expected values on 96 × 64 frames: RMS error 1.75e-2 / 4.1e-3 / 1.25e-2 of the peak (Siemens star / slanted edge / zone plate) at 4, 6.1e-3 / 1.1e-3 / 2.1e-3 at 8; cost on a 384 × 256 DNG 43 / 53 / 90 / 242 ms at 1 / 2 / 4 / 8. `sensor.temporalSampleCount` (default 8 when moving) against 64: RMS error 0.125 (subject, a long streak) and 0.18 (rotation) at 8, 0.074 and 0.096 at 16; a 384 × 256 DNG with a moving subject 6.8 / 13.2 / 25.9 / 51.3 s at 4 / 8 / 16 / 32. The error follows the streak length, so a fixed count cannot bound it; both defaults are left as they are and the choice is put to the owner. Diffraction radius and bokeh zones stay exact-only. Tests: `test/spectral-step-default.test.ts` (new).
+
+### #593, #601, #602 Display view: luminance tone curves, highlight reconstruction, desaturation
+
+- **New (#593):** `simulateDisplayView` and `prepareDisplayView` render the luminance tone curves (`extended-reinhard-luminance`, `naka-rushton-luminance` with `toneCurveParameters`) and `output.highlightMode: "reconstruct"`, which they refused through 2.21.0. Photivra's own looks for the app: Standard (Naka–Rushton n = 1.5, Lw = 8, σ = 0.5009) and Flat (n = 1, Lw = 32, σ = 0.8465), both keeping 18 % gray at 0.18; request parameters, not engine presets. A tone curve's moments come from conditioning each developed component on luminance; `reconstruct` (and #601's desaturation), where a pixel reaches it, from a 3-D Gauss–Hermite rule over the whole development chain (`src/facade/display-view-rendering.ts`; docs/DISPLAY_VIEW.md, "Coupled rendering"). Reported in the assumption `view.rendering`.
+- **New (#601):** `output.gamutHandling: "desaturate-to-luminance"` (opt-in; default `"clip-components"`) and the same value of `SdrRenderingProfile.gamutHandling`: after the tone curve, a pixel whose largest component exceeds 1 moves toward the gray of its own luminance until that component is 1, keeping luminance and hue. sRGB rendering only; captures (CPU), the display view (CPU and GPU). The image-kernel accelerator's WebGPU SDR kernels refuse it (`unsupported-on-backend`; their fallback runs the CPU reference).
+- **New (#602):** `output.highlightMode: "reconstruct-neighbors"` (opt-in, an estimate): clipped channels rebuilt from the color ratios of the unclipped pixels around each clipped region (widened by 2 pixels, whose demosaic reads clipped sites): the ring's mean ratios (fast) or their harmonic interpolation inward (full). Captures, the ideal reference and the CPU display view; not with `output.region`; not on the GPU in 2.22.0 (`unsupported-on-backend`). `RawHighlightDiagnostics.mode` gains the value; `SensorColorDevelopment` gains `developWhiteBalancedInto`.
+- **GPU (#593, #601):** the Speed kernel and the Quality pixel pass run the luminance tone curves (every exponent), `reconstruct` and the desaturation, with the fast and the full rules, from one on-demand WGSL module (`src/gpu/wgsl-display-view-coupled.ts`) with first-order running bounds (docs/WEBGPU.md, "Coupled rendering steps"); undecided threshold decisions are recomputed on the host. Measured on the float32 emulation and on a hardware adapter (Apple, Metal 3): every component inside its bound, at most one code.
+- **Speed versus accuracy:** registry entries `output.toneCurve/view-luminance-moments` (fast: 8-point Gauss–Hermite in luminance; full: composite 4 × 16-point Gauss–Legendre), `output.highlightMode.reconstruct/view-moments` (fast: 6 points per axis; full: 16), `prepareDisplayView.gpu/view-coupled-moments` (the GPU kernels with either rule) and `output.highlightMode.reconstruct-neighbors/region-ratios` (fast: ring mean; full: harmonic fill). Fast on screen, full for exports and `fast: false`. Measured fast-versus-full gaps: tone 6.7·10⁻⁶; chain 1.5·10⁻² linear at channel σ up to 0.076 (2.4·10⁻⁴ at σ ≤ 0.01).
+- **On demand:** the coupled steps and the neighbor reconstruction load with the CPU Quality kit (#594), and the GPU coupled steps (`src/gpu/wgsl-display-view-coupled.ts`) on their own, only for requests that ask for them; the default path imports their types and a 0.9 KB WGSL stub only.
+- **Unchanged:** requests without these options are byte-identical (the display-view hash locks pass unchanged).
+- **Size (owner decision: no trimming; the code moves on demand with #594):** measured on the part alone, the display view's added entry size was 49,573 B minified (budget 46,500 B); after the #594 split it is 38,370 B (see "#594 On-demand Quality code").
+- **Tests:** `test/display-view-coupled-rendering.test.ts`, `test/display-view-coupled-gpu.test.ts`, `test/neighbor-highlight-reconstruction.test.ts` (new); coupled cases in `test/display-view-speed-gpu.test.ts`, `test/webgpu/display-view.webgpu.ts` and `test/fast-methods-registry.test.ts`.
+
+### The display view's AHD low-signal correction removed; per-site wording
+
+The owner decided (2026-11-11) to drop the display view's AHD low-signal correction, which was kept as precomputed values on a grid of the three channel signal levels. Computing it per site at use instead was measured at about 240–1300× the view's time (one evaluation 18 ms with 2048 draws, 74 ms with 8192), so the correction is removed on every path rather than replaced. The view's signals stay integrated per site at use.
+
+- **Changed (default change, display view with `output.demosaic: "ahd"`):** no low-signal correction on the CPU (fast and `fast: false`) or in the GPU Quality kernel. `view.demosaic` is now `{ capture: "ahd", view: "ahd-candidates-with-noise-free-choice", lowSignalNoiseChoice: "not-modelled", scientificStatus: "approximation", measuredBias8BitCodes }` (before: `ahd-candidates-with-low-signal-correction` with `correctedPixels`, `correctionDrawsPerState` and `correctionThresholdLinearStd`). Measured shift of the view against 2.21.0, mean over a centred 32 × 32 block at f/8: 1.4 µm at ISO 6400, red +3.8 to +4.6 codes (8-bit; at most 6.7 in a pixel); 6 µm at ISO 6400, within 0.3 code; the app's 6 µm ISO 400 Quality request, within 0.01 code. A view without AHD, or whose pixels' noise stayed under the old 0.01 threshold, is byte-identical.
+- **Changed (fast methods):** the registry entry `output.demosaic.ahd/view-low-signal-correction` is removed; AHD has no fast method in the view either, so `diagnostics.fast.applied["output.demosaic.ahd"]` is false and an AHD view on its own reports `assurance: "engine-reference"` (the approximation is labelled in `view.demosaic`). `fast` and `fast: false` give the same AHD view.
+- **Deprecated (kept until 3.0.0, documented in docs/DISPLAY_VIEW.md, "AHD at low signal"):** `serializeDisplayViewCorrectionStates()` returns `[]`; `bindDisplayViewCorrectionStates(entries)` checks its entries as before and returns 0; `prepared.correctionKey()` returns null; `prepared.collectCorrectionStates(view)` and `prepared.computeCorrectionStates(gridKeys)` check their arguments as before and return no keys or states; `diagnostics.ahdCorrectedPixelCount` is always 0. The types `DisplayViewCorrectionStateSet` and `DisplayViewCorrectionStateKeys` stay. No root export is removed.
+- **Changed (label only):** the capture's per-site expected-signal path (#394) reports `raw.expectedSignal` `method: "per-site-integrated-electrons"` (before: `tabulated-expected-electrons`); its explanation says each site's electrons are integrated from its materials' spectra when the site is read, as since 2.21.0. RAW codes and samples are unchanged.
+- **Tests:** the display view's uniform AHD hash lock (the one case where the correction applied) is re-recorded on x64 and arm64; the low-signal AHD comparison against the capture takes a 5-code limit for the 1.4 µm ISO 6400 case (4.25 measured); the state-exchange tests become one deprecation test; the GPU Quality tests drop the state-store test.
+
+- **Changed (label only):** `lens.catalogue`'s fast method is described as what it has done since 2.21.0: each site's expected electrons are integrated from its taps' material spectra when the site is read. The `raw.expectedSignal` assumption's `method` of a capture that took this fast method is now `per-site-integrated-electrons-catalogue-psf-field-grid` (before: `tabulated-expected-electrons-catalogue-psf-field-grid`); its explanation and the fast-methods registry entry `lens.catalogue/field-grid` say the same. Samples, RAW codes and every other assumption field are unchanged. Code that matched the old `method` string must match the new one.
+
+### #165 Content Credentials writers (engine half)
+
+- **New (#165, engine half):** `bindC2paManifestStore`, `calculateC2paDataHash`, `setC2paManifestStore` and `parseC2paManifestStore` embed a caller-built C2PA Manifest Store in a JPEG (APP11 segments right after APP0, as the reference SDK writes them, C2PA 2.4 §A.3.1), PNG (a `caBX` chunk right after IHDR, §A.3.2) or DNG/TIFF (tag 52545 in the main IFD, store at the end of the file, §A.3.6); return the `c2pa.hash.data` exclusions (§18.5.3: every C2PA APP11 segment; §18.5.4: the whole caBX chunk; §18.5.5: the entry's count field and the store); compute the SHA-256 over the bound bytes; write the signed store in place at exactly the placeholder's length (§10.4), so no offset moves; and find an existing store and its binding without verifying signatures. `C2PA_ALGORITHMIC_MEDIA_SOURCE_TYPE` (owner decision: IPTC `algorithmicMedia`) and `C2PA_MANIFEST_STORE_MAXIMUM_BYTES` (32 MiB). No keys, signing, manifest building or network calls in the engine. See [Content Credentials](https://github.com/Photivra/photivra/blob/main/docs/CONTENT_CREDENTIALS.md).
+- **Root exports:** 15 new (6 runtime: 4 functions, 2 constants; 9 types). Nothing is removed and no existing output changes.
+- **Sizes:** the app's capture-worker shape is unchanged by this part (the module is imported by nothing in the capture path; `test/capture-bundle.test.ts` asserts it stays out). An application importing the four functions adds 4,883 B gzip (11,978 B minified; rolldown 1.2.9).
+- **Pending:** validation of signed files with the C2PA reference tooling (no validator offline, and the engine cannot sign).
+
+### #594 On-demand Quality code
+
+- **Changed (bundling, #594):** the display view's GPU Quality host and its WGSL (`display-view-quality-gpu.ts`,
+  `wgsl-display-view-quality-kernel.ts`, `wgsl-exact-sum.ts`) load on demand, at the first GPU render that takes the Quality
+  passes (diffraction, AHD, more query offsets than the Speed kernel holds, a defocused view, an image-plane print). The combined
+  renderer moves to `src/gpu/display-view-gpu-renderer.ts`; the Speed path no longer imports the Quality host. Results are
+  unchanged: GPU renders through `prepareDisplayView` on the float32 emulation (two Quality, two defocus and one Speed request)
+  give the same sample and bound hashes before and after.
+- **Changed (diagnostics timing, owner decision 2026-11-10):** the Quality kernels' two self-check cases run before a view's
+  first Quality render instead of before its first GPU render. A Speed-only view's `conformance.cases` lists the two built-in
+  cases and the Speed case; a view that takes the Quality passes appends the two Quality cases. A failure keeps that render and
+  every later one on the CPU, labelled `conformance-failed`. Internal: the renderer contract gains `onDemandConformanceCases`.
+- **New:** `prepareQualityPaths()` (root export; owner decision 2026-11-10) loads the on-demand full-quality code ahead of time,
+  for example when the user opens Export. Optional, single flight, idempotent, no change to results; a failed load rejects with
+  `ImageKernelExecutionError` reason `quality-code-unavailable` and is retried by the next call or request. It loads the GPU
+  Quality chunk and the two CPU kits.
+- **New fallback reason:** `quality-code-unavailable` (in `DisplayViewGpuFallbackReason` and `ImageKernelFailureReason`). If the
+  Quality chunk does not load, that render runs the CPU reference (the same full-quality result, slower), labelled; with
+  `gpu: "require"` it fails with that reason. Not sticky: the next render that needs the code loads it again. A failed
+  self-check stays sticky.
+- **Changed (bundling, CPU, #594):** the CPU full-quality code is one on-demand chunk, the Quality kit (`src/facade/quality-kit.ts`:
+  diffraction, the capture's AHD demosaic, `lens.defocus` beyond the geometric disc (bokeh shapes, cat's eye, the large-disc
+  lattice) and the image-space provider (lens projection, distortion, vignetting, rotation, a moving subject), the display view's
+  coupled rendering steps and the neighbor highlight reconstruction), and the opt-in features another, the opt-in kit
+  (`src/facade/opt-in-kit.ts`: `sensor.profile`, `illumination`, `motion.subject`). Each loads once where the request is parsed
+  and is then called synchronously; every hash lock passes. The app's geometric-disc focus control stays on the fast path. Not
+  moved: the native-photosite report (#595; every capture reports it), the exposure build-up hooks (255 B, in the RAW
+  producers) and the display view's inline AHD candidates. `ImageKernelExecutionError` moves to `src/core/execution-error.ts`
+  (re-exported unchanged) so the loader adds no GPU code to the first load.
+- **Size (app capture-worker shape, rolldown 1.2.9, gzip 9):** after the GPU split, fast worker 363,695 → 344,287 B and GPU
+  Quality chunk 20,026 B on demand (all chunks +618 B: two chunks compress separately; owner-accepted). With every part merged
+  the fast worker measured 358,680 B; after the CPU split it is **337,413 B** and on demand **46,977 B** (GPU Quality 19,401 B,
+  CPU Quality kit 18,249 B, GPU coupled steps 5,159 B, opt-in kit 4,168 B); all chunks 384,390 B. `test/capture-bundle.test.ts`
+  checks the owner's two rows, each its measurement rounded up to the next 100 B (owner answer, 2026-11-10): fast worker
+  ≤ 337,500 B, on demand ≤ 47,000 B, in place of 2.21.0's 363,700 B all-chunk limit. The bundler now gives the entry ten small
+  chunks it shares with the kits, so the display view's added size is measured on the entry and those chunks: 38,370 B minified
+  and 14,126 B gzip (budgets 46,500 B and 18,550 B, unchanged; 2.21.0: 46,270 B and 18,327 B). The app adopts the two rows
+  at app round 16.
+- **Root exports:** 1 new (runtime): `prepareQualityPaths`.
+
+## 2.21.0 — published November 10, 2026
 
 A minor release that combines the 2.21.0 and 2.22.0 parts (owner decision 2026-11-10): the chart-signal design choice on every render path, sensor profiles and phone lenses (#554), the image-plane scene (#581), catalogue-lens boundary ties (#588) and lateral color (#589), exposure build-up (#534) with subject motion (#551) and mixed lighting (#550), the lateral color fringe width (#580), Photivra's own light-source spectra (#557) and the print planner's contain fit (#365). See the [2.21.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_21_0.md).
 

package/CITATION.cff

@@ -9,7 +9,7 @@ abstract: "An open TypeScript engine for the science and mathematics of photogra
 repository-code: "https://github.com/photivra/photivra"
 url: "https://photivra.com"
 license: "Apache-2.0"
-version: "2.21.0"
+version: "2.22.0"
 keywords:
   - photography
   - camera optics

package/README.md

@@ -32,10 +32,10 @@ The source is licensed under Apache-2.0.
 
 ## Quick start
 
-Install the published ESM package below. The [2.21.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_21_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
+Install the published ESM package below. The [2.22.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_22_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
 
 ```sh
-npm install @photivra/engine@2.21.0
+npm install @photivra/engine@2.22.0
 ```
 
 Simulate a photograph of a test chart with a generic camera, then read the developed sRGB pixels:
@@ -75,7 +75,7 @@ console.log(horizontal.provenance);
 
 Start with the [Developer Guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Then use the [Usage Guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md) and the [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md), which is generated from the package exports.
 
-Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.21.0` tag.
+Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.22.0` tag.
 
 ## Documentation
 
@@ -363,14 +363,14 @@ The application can then use those results, while the photography calculations t
 
 ## Status
 
-- Repository package version: `2.21.0` (release candidate prepared November 10, 2026; publication is separate)
-- Engine API contract: `2.21.0`
+- Repository package version: `2.22.0` (release candidate prepared November 11, 2026; publication is separate)
+- Engine API contract: `2.22.0`
 - Versioned generic tier reference assets: [GENERIC_TIER_PRESETS.md](https://github.com/Photivra/photivra/blob/main/docs/GENERIC_TIER_PRESETS.md).
 - Sensor profiles from published specifications (#554, unnamed): [SENSOR_PROFILES.md](https://github.com/Photivra/photivra/blob/main/docs/SENSOR_PROFILES.md).
 - Composed POC simulation API contract: `1.0.0`
 - Stability: 1.0 root-package compatibility policy; bounded scientific models and independent POC contract
 
-From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.21.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
+From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.22.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
 
 A breaking change to the root contracts now needs a new package major version. Additive and corrective changes follow [compatibility and migration](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_1_3_0.md). A 1.0 package is not a claim of calibrated physical accuracy.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ Please do not open a public issue that contains vulnerability details.
 
 ## Supported versions
 
-The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.20.0**, published on November 10, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
+The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.21.0**, published on November 10, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
 
 Security fixes target the current maintained development and release line. Do not assume that older 1.x releases, snapshots or pre-1.0 releases will receive fixes.
 

package/THIRD_PARTY.md

@@ -14,11 +14,20 @@ This file records direct development and CI dependencies intentionally used by t
 | Vitest | 5.0.1 | Unit/integration testing | MIT |
 | @vitest/coverage-v8 | 5.0.1 | V8-backed test coverage | MIT |
 | rolldown | 1.2.9 | Bundling test of capture-only consumers (`test/capture-bundle.test.ts`) | MIT |
+| jxl-oxide-wasm | 0.12.6 | JPEG XL tile decoding in the phone DNG import tests (`test/dng-import-phone.test.ts`); see [JPEG XL](#jpeg-xl-2220) | MIT OR Apache-2.0 |
 | actions/checkout | v7 / `3d3c42e5aac5ba805825da76410c181273ba90b1` | CI checkout | MIT |
 | actions/setup-node | v7 / `820762786026740c76f36085b0efc47a31fe5020` | CI Node setup | MIT |
 | actions/upload-artifact | v7.0.1 / `043fb46d1a93c77aae656e7c1c64a875d1fc6a0a` | Verified release artifact transfer | MIT |
 | actions/download-artifact | v8.0.1 / `3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c` | Verified release artifact retrieval | MIT |
 
+## JPEG XL (2.22.0)
+
+DNG 1.7 phone files may store their raw data as JPEG XL (Compression 52546; #598). The owner chose the jxl-oxide decoder (owner, 2026-11-10), as its prebuilt WebAssembly package from npm, `jxl-oxide-wasm` 0.12.6 (<https://github.com/tirr-c/jxl-oxide>), dual-licensed MIT OR Apache-2.0. **Chosen licence: Apache-2.0** (owner-accepted 2026-11-11, with the licence check's rule that an SPDX `OR` expression passes when one choice is allowed). It is a **devDependency only**: the published package declares no runtime dependency and does not import it. `createJxlOxideDngDecoder` takes the module the application loaded (structurally typed), so an application that opens JPEG XL DNGs installs and lazily loads jxl-oxide-wasm itself, and its licence then applies to that application. No jxl-oxide source is vendored or copied. `scripts/check-license-policy.mjs` accepts an SPDX `OR` expression when one of its choices is on the allowlist (here Apache-2.0 and MIT both are).
+
+Patents (rule 2; not legal advice): JPEG XL is ISO/IEC 18181. At the 2026-11-10 research (#598), royalty-free patent declarations on JPEG XL had been filed by Google and Cloudinary only; Google's patent grant text covers its own implementations (libjxl, jxl-rs), not jxl-oxide. The owner accepted jxl-oxide on that basis (2026-11-10). The engine itself contains no JPEG XL coding: its tests carry a small test-only lossless encoder (`test/helpers/phone-dng-fixtures.ts`, written from ISO/IEC 18181-1:2022, modular mode with the zero predictor and prefix codes) to build fixtures, never shipped.
+
+The 2.22.0 DNG opcode, ProfileGainTableMap and RGBTables readers (`src/capture/dng-opcodes.ts`, `dng-profile-maps.ts`) were written from the DNG specification's tag descriptions; because the 1.7.1.0 PDF could not be downloaded (HTTP 403), their byte layouts and evaluation order were only checked by reading the Adobe DNG SDK 1.7.1 source. No code was copied from the DNG SDK (layouts and behaviour checked only; the engine's code is written independently); the PDF check is pending with the owner; the Adobe DNG notice in `NOTICE` covers the DNG technology.
+
 Node built-in modules are used only by development tooling and the repository-local POC API; that API is excluded from the published package and the built-ins are not third-party dependencies.
 
 `src/sensor/stochastic-seed.ts` independently implements the MurmurHash3_x86_32 algorithm and its `fmix32` finalizer (Austin Appleby). The upstream `MurmurHash3.cpp` header states the algorithm "is placed in the public domain" and disclaims copyright. The SMHasher test suite that contains it is a separate work: its README says "SMHasher is released under the MIT license". No SMHasher or MurmurHash3 source file is vendored or copied. `test/sensor-raw-noise-independence.test.ts` reimplements, in its own code, SMHasher's verification procedure (keys of 0–255 bytes hashed with seed 256 − i, then the hash of those hashes) and compares the result with the published MurmurHash3_x86_32 verification value 0xB0F57EE3, a published fact. Test vectors earlier copied from a Stack Overflow answer (CC BY-SA 3.0) were removed.
@@ -27,6 +36,8 @@ Node built-in modules are used only by development tooling and the repository-lo
 
 `src/optics/longitudinal-chromatic-aberration.ts` uses three physical constants: the Fraunhofer d (helium, 587.5618 nm), F (hydrogen, 486.1327 nm) and C (hydrogen, 656.2725 nm) spectral-line wavelengths used to define the Abbe number (as tabulated in SCHOTT Technical Information TIE-29, *Refractive Index and Dispersion*, 2023, free; also the reference wavelengths of ISO 7944). They are factual measured constants of nature, not a copied dataset or table; no glass catalogue data is included and refractive index and Abbe number are caller inputs. The 2.0 projection, distortion, Zernike/Seidel, vignetting, polarizer and haze models are independent implementations of published equations cited in `docs/PHYSICS_FOUNDATION.md` and `docs/PSF_FOUNDATION.md`; they contain no third-party code or numeric tables.
 
+`src/capture/c2pa-embed.ts` (#165) is written from the C2PA Technical Specification 2.4 (free, published by the C2PA) and ISO 19566-5 box framing as that specification describes it. To produce the same JPEG and PNG bytes as the C2PA reference SDK, it uses interoperability facts read from c2pa-rs `sdk/src/asset_handlers/jpeg_io.rs` and `png_io.rs` (MIT OR Apache-2.0): the 64,000-byte split of the store across APP11 segments, the box instance number `En` = 0x0211 and the segments' place right after the last APP0 (or SOI); and the PNG `caBX` chunk's place right after IHDR with the whole chunk excluded. No c2pa-rs source is vendored or copied, and nothing is a runtime dependency. Checking a signed file with the C2PA reference validator is pending (docs/RELEASE_2_22_0.md, "Pending"); the engine signs nothing and makes no network request.
+
 This inventory does not replace a transitive dependency/SBOM review before a release. New runtime dependencies, scientific datasets, model weights, or calibration material require explicit provenance and license review.
 
 ## Pending licence and source reviews

package/dist/capture/c2pa-embed.d.ts

@@ -0,0 +1,116 @@
+/** IPTC digital source type for media created purely by an algorithm (https://cv.iptc.org/newscodes/digitalsourcetype/). */
+export declare const C2PA_ALGORITHMIC_MEDIA_SOURCE_TYPE: "http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia";
+/** Largest manifest store the engine embeds or reads, bytes (an engine limit, not a C2PA one). */
+export declare const C2PA_MANIFEST_STORE_MAXIMUM_BYTES = 33554432;
+/** A byte range of a file: `start` is a zero-based offset, `length` a byte count. */
+export interface C2paByteRange {
+    start: number;
+    length: number;
+}
+/**
+ * Where the manifest store sits in a file and which bytes the data hash excludes. Plain data: it can be kept, sent to a
+ * worker or serialized, and must be passed back unchanged to `setC2paManifestStore`.
+ */
+export interface C2paHardBinding {
+    /** `image/jpeg`, `image/png`, or for TIFF files `image/dng` when the main IFD has DNGVersion (50706), otherwise `image/tiff`. */
+    mediaType: "image/jpeg" | "image/png" | "image/dng" | "image/tiff";
+    /** Length of the file with the store embedded, bytes. */
+    fileLength: number;
+    /** The `exclusions` of the `c2pa.hash.data` assertion, ascending and non-overlapping (§18.5). */
+    exclusions: readonly C2paByteRange[];
+    /** JPEG: every C2PA APP11 segment, markers and length fields included. PNG: the whole caBX chunk. TIFF/DNG: the store's own bytes. */
+    manifestRegion: C2paByteRange;
+    /** Length of the JUMBF manifest store itself, bytes. A replacement store must have exactly this length. */
+    manifestStoreLength: number;
+}
+/** A file with a manifest store embedded, and its binding. */
+export interface C2paBoundFile {
+    bytes: Uint8Array;
+    binding: C2paHardBinding;
+}
+/** A manifest store found in a file (`parseC2paManifestStore`): its binding and a copy of the store's JUMBF bytes. */
+export interface C2paFoundManifestStore {
+    binding: C2paHardBinding;
+    manifestStore: Uint8Array;
+}
+/** Input of `bindC2paManifestStore`. */
+export interface BindC2paManifestStoreInput {
+    /** A JPEG, a PNG, or a TIFF-based file such as a DNG, as written by the engine's exporters. It is read, never changed. */
+    file: Uint8Array;
+    /**
+     * The placeholder store (§10.4): a JUMBF C2PA Manifest Store sized for the final signature. For JPEG it may instead be the
+     * same store already split into APP11 segments (what the C2PA reference SDK's placeholder call returns), as long as that
+     * split is the one described above.
+     */
+    manifestStore: Uint8Array;
+}
+/** Input of `setC2paManifestStore`. */
+export interface SetC2paManifestStoreInput {
+    /** The bound file (`C2paBoundFile.bytes`). It is read, never changed. */
+    file: Uint8Array;
+    /** The binding `bindC2paManifestStore` (or `parseC2paManifestStore`) returned for it. */
+    binding: C2paHardBinding;
+    /** The final, signed store: exactly `binding.manifestStoreLength` bytes, as JUMBF or (JPEG) in the same APP11 split. */
+    manifestStore: Uint8Array;
+}
+/** Input of `parseC2paManifestStore`. */
+export interface ParseC2paManifestStoreInput {
+    /** A JPEG, PNG or TIFF-based file such as a DNG. It is read, never changed. */
+    file: Uint8Array;
+}
+/** Input of `calculateC2paDataHash`. */
+export interface CalculateC2paDataHashInput {
+    /** The bound file. */
+    file: Uint8Array;
+    /** The binding's exclusions (or any ascending, non-overlapping ranges inside the file). */
+    exclusions: readonly C2paByteRange[];
+}
+/** SHA-256 over every byte of the file outside the exclusions, in file order (§18.5): the `hash` of `c2pa.hash.data`. */
+export interface C2paDataHash {
+    alg: "sha256";
+    hash: Uint8Array;
+    hashHex: string;
+    hashedByteCount: number;
+}
+/**
+ * Embeds a placeholder C2PA Manifest Store in a JPEG, PNG or TIFF/DNG export and returns the new file with its hard binding:
+ * the exclusions for `c2pa.hash.data` and where the store sits (C2PA 2.4 §A.3.1, §A.3.2, §A.3.6, §18.5, §10.4; see the module
+ * notes). The input file is not changed. Only the first store of a file can be added; a file that already has one is rejected.
+ * @param input - The file and the placeholder store.
+ * @returns The bound file (a new array) and its binding.
+ *
+ * @see docs/CONTENT_CREDENTIALS.md for the workflow and the byte layouts.
+ */
+export declare function bindC2paManifestStore(input: BindC2paManifestStoreInput): C2paBoundFile;
+/**
+ * Finds the C2PA Manifest Store embedded in a JPEG (APP11), PNG (caBX) or TIFF/DNG (tag 52545) and returns its location as a
+ * binding (the exclusions the engine's own writer uses for that format) and a copy of the store. It checks the file's structure
+ * and the store's outer framing only: it does not read the manifests, check the data hash or verify any signature. The
+ * manifest's own `c2pa.hash.data` assertion is what a validator uses; this binding is what `setC2paManifestStore` needs.
+ * @param input - The file.
+ * @returns The store and its binding, or null when the file has none.
+ *
+ * @see docs/CONTENT_CREDENTIALS.md for the byte layouts.
+ */
+export declare function parseC2paManifestStore(input: ParseC2paManifestStoreInput): C2paFoundManifestStore | null;
+/**
+ * Writes the final, signed manifest store over the placeholder of a bound file (C2PA 2.4 §10.4.4). The store must have
+ * exactly the placeholder's length, so the file's length, every offset and every byte outside the exclusions stay the same
+ * and the data hash computed before signing still holds. The binding is checked against the file first. The new store goes
+ * into the file's existing segments or chunk as they are (for PNG the chunk CRC is recomputed; it is inside the exclusion).
+ * @param input - The bound file, its binding and the signed store.
+ * @returns A new array: the file with the signed store.
+ *
+ * @see docs/CONTENT_CREDENTIALS.md for the workflow.
+ */
+export declare function setC2paManifestStore(input: SetC2paManifestStoreInput): Uint8Array;
+/**
+ * SHA-256 over every byte of a file outside the given exclusions, in file order: the value of `hash` in a `c2pa.hash.data`
+ * assertion with `alg` "sha256" (C2PA 2.4 §18.5). It uses Web Crypto (`crypto.subtle`, browsers in secure contexts and
+ * Node 22+). The bytes outside the exclusions are copied once into one array before hashing.
+ * @param input - The file and its exclusions (ascending, non-overlapping, inside the file).
+ * @returns The digest as bytes and hexadecimal, and how many bytes it covers.
+ *
+ * @see docs/CONTENT_CREDENTIALS.md for the workflow.
+ */
+export declare function calculateC2paDataHash(input: CalculateC2paDataHashInput): Promise<C2paDataHash>;