@photivra/engine 2.20.0 → 2.22.0

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

@@ -58,10 +58,13 @@ export interface DisplayViewGpuConformance {
 2.11 (#481): why a display view that asked for the GPU (`gpu: "auto"`) ran the CPU reference. The accelerator's acquisition
 reasons, plus: `unsupported-on-backend` (no GPU display-view renderer exists in this version, or it does not support the
 request), `conformance-failed` (the device failed the run-time self-check before the view's first GPU render), `device-lost`
-(the device was lost; the rest of the view runs on the CPU) and `disposed` (the prepared view was disposed).
+(the device was lost; the rest of the view runs on the CPU) and `disposed` (the prepared view was disposed). 2.22.0 (#594):
+`quality-code-unavailable` (the on-demand GPU full-quality code could not be loaded; that render runs the CPU reference, and
+the next render that needs the code tries to load it again).
 
 ```ts
-export type DisplayViewGpuFallbackReason = ImageKernelFallbackReason | "unsupported-on-backend" | "conformance-failed" | "device-lost" | "disposed";
+export type DisplayViewGpuFallbackReason = ImageKernelFallbackReason | "unsupported-on-backend" | "conformance-failed" | "device-lost" | "disposed" |
+  "quality-code-unavailable";
 ```
 
 ## DisplayViewGpuMode

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

@@ -4,14 +4,10 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 ## bindDisplayViewCorrectionStates
 
-2.10 (#447): adds states another realm computed (an export, or `computeCorrectionStates` results) to this realm's cache and
-returns the number of states added. For each entry, the grid keys its setup does not hold yet are appended; known ones are
-left as they are (a state's values follow from its key, so they are equal). Every entry is checked before the cache is
-touched: `key` a non-empty string, `gridKeys` an Int32Array of grid keys, `values` a Float64Array of 3 × `gridKeys.length`
-finite numbers; otherwise it fails with an InvalidConfigurationError and the cache is unchanged. The cache's bounds apply as
-in a render: an unknown key creates a setup and can evict the least recently used of the four kept, and a setup that
-reaches 65 536 states is cleared before the next one is added. Import only keys a prepared view reported
-(`correctionKey()`), so states a render here will read.
+2.10 (#447), deprecated in 2.22.0: added states another realm computed to this realm's cache. The display view keeps no
+correction states since 2.22.0, so this checks `entries` as before (an array of `{ key, gridKeys, values }` with a non-empty
+string key, an Int32Array of grid keys and a Float64Array of 3 finite values per key; otherwise an
+InvalidConfigurationError) and returns 0: nothing is stored and no render reads them. Kept until 3.0.0.
 
 ```ts
 export function bindDisplayViewCorrectionStates(entries: readonly DisplayViewCorrectionStateSet[]): number;
@@ -21,7 +17,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## DisplayViewCorrectionStateKeys
 
-2.10 (#447): the grid keys of the states a region needs (`PreparedDisplayView.collectCorrectionStates`), ascending.
+2.10 (#447), deprecated in 2.22.0: the grid keys of the states a region needs (`PreparedDisplayView.collectCorrectionStates`).
 
 ```ts
 export interface DisplayViewCorrectionStateKeys { key: string; gridKeys: Int32Array }
@@ -29,9 +25,9 @@ export interface DisplayViewCorrectionStateKeys { key: string; gridKeys: Int32Ar
 
 ## DisplayViewCorrectionStateSet
 
-2.10 (#447): the AHD low-signal correction states of one setup, as a realm sends them to another. `key` is the setup's
-correction key (`PreparedDisplayView.correctionKey()`), `gridKeys[i]` a state's grid key and `values[3·i …]` its three
-values (28 bytes per state). Both arrays are transferable.
+2.10 (#447), deprecated in 2.22.0: the AHD low-signal correction states of one setup, as a realm sent them to another. The
+display view keeps no correction states since 2.22.0, so {@link serializeDisplayViewCorrectionStates} returns none.
+Kept until 3.0.0.
 
 ```ts
 export interface DisplayViewCorrectionStateSet { key: string; gridKeys: Int32Array; values: Float64Array }
@@ -39,9 +35,9 @@ export interface DisplayViewCorrectionStateSet { key: string; gridKeys: Int32Arr
 
 ## serializeDisplayViewCorrectionStates
 
-2.10 (#447): the AHD low-signal correction states this JavaScript realm holds (a Web Worker, a page), one entry per cached
-setup, least recently used first, each state's grid key and three values copied out. Another realm adds them with
-{@link bindDisplayViewCorrectionStates}; a render there then reads them instead of computing them, with the same bytes.
+2.10 (#447), deprecated in 2.22.0: returned the AHD low-signal correction states this realm held. The display view keeps no
+correction states since 2.22.0 (the correction was removed; docs/DISPLAY_VIEW.md, "AHD at low signal"), so this returns an
+empty array. Kept until 3.0.0.
 
 ```ts
 export function serializeDisplayViewCorrectionStates(): DisplayViewCorrectionStateSet[];

package/docs/api/facade-exposure-build-up.md

@@ -0,0 +1,105 @@
+# facade/exposure-build-up.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS
+
+The most fractions one build-up takes.
+
+```ts
+EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS = 64
+```
+
+## EXPOSURE_BUILD_UP_STREAM_BASE
+
+The first stream ID of the build-up's per-site random streams (`deriveNativeSiteStreamSeedUint32`): fraction j's photo split,
+dark split and readout use streams base + 3j, + 3j + 1 and + 3j + 2 (j = 0 … 63). The whole exposure keeps the ordinary
+streams 0 (charge) and 1 (read noise).
+
+```ts
+EXPOSURE_BUILD_UP_STREAM_BASE = 0x42550000
+```
+
+## simulateExposureBuildUp
+
+Renders fractions of one exposure as one accumulating process (#534), the way a camera's live readout of a long exposure
+would show the light building up. Each fraction is read out and developed as its own photo.
+
+The model: photon and dark-charge arrivals at a site are Poisson processes (photon shot noise: EMVA 1288 Release 4.0,
+section 2, free), with any rate over time. Given the count n over [0, t] of a Poisson process with mean Λ(t), its arrival
+times are n independent times with distribution Λ(s)/Λ(t) on [0, t], so its count over [0, s] is Binomial(n, Λ(s)/Λ(t))
+(R. G. Gallager, Discrete Stochastic Processes, chapter 2, sections 2.4 and 2.5, MIT OpenCourseWare 6.262, free).
+
+The method: the whole exposure is `simulateCapture(options)` itself, with its ordinary draws and seeds. Each earlier fraction
+fⱼ is a capture of the same request in manual mode at the whole exposure's resolved f-number and ISO and the shutter fⱼ·t,
+so its expected signal at every site is integrated from the spectrum over the window [0, fⱼ·t] by the capture itself (the
+camera rotation, `motion.subject` and mixed lighting included, and each row's own window with a rolling shutter). Its
+counts are not drawn anew: going down the fractions, each site's photo and dark counts are N(fⱼ) ~ Binomial(N(fⱼ₊₁), λ(fⱼ) /
+λ(fⱼ₊₁)), with λ the site's expected mean in each render (after PRNU and DSNU). So every fraction's counts are Poisson with
+that fraction's own mean (the mean and variance of `simulateCapture` at fⱼ·t), they never decrease from one fraction to the
+next, and two fractions' counts covary by the earlier one's mean. Fixed-pattern noise is the sensor's own and the same in
+every fraction. Each fraction's charge is clipped at the full well, then read once: its own read noise (dual gain as the ISO
+selects), pre-ADC and ADC saturation and quantization at the ADC bit depth.
+
+The windows are nested, so the true means never decrease; the capture's temporal midpoint quadrature can still put an
+earlier fraction's estimate above a later one's at a site (motion blur). There the split takes probability 1 (the count is
+kept), and the `exposure.buildUp` assumption counts those sites (`nonMonotoneSites`): an approximation of the quadrature,
+not of the binomial law. Raise `sensor.temporalSampleCount` to remove them.
+
+Cost: one capture per fraction, plus about 64 bytes per native site for the chain. Exact or fast: the request's own `fast`
+(and the format default) applies to every fraction; the build-up adds no fast method, so with `fast: false` (the calculator's
+setting) every fraction is an exact capture. On screen only: formats "srgb-8" and "srgb-16" (a fraction's JPEG, PNG or DNG
+is refused). A fraction's realization depends on the whole `fractions` list (each step of the chain has its own streams);
+the same request and list always give the same frames.
+
+```ts
+export async function simulateExposureBuildUp(options: SimulateCaptureOptions, buildUp: SimulateExposureBuildUpOptions): Promise<SimulateExposureBuildUpResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## SimulateExposureBuildUpFrame
+
+One readout of a build-up.
+
+```ts
+export interface SimulateExposureBuildUpFrame {
+  /** The fraction of the exposure collected. */
+  fraction: number;
+  /** fraction × the request's shutter time, in s. */
+  elapsedSeconds: number;
+  /**
+   * The fraction developed as its own photo. At fraction 1 it is `simulateCapture(options)` itself, byte for byte. Below 1 it is
+   * the result of the fraction's capture (manual, the whole exposure's f-number and ISO, shutter fraction·t: its `image`, `raw`,
+   * `plan` and `request`), with the build-up's counts, the `exposure.buildUp` assumption, and the whole exposure's `exposure` and
+   * `sensor` reports (the camera's settings and noise figure, not the elapsed part's).
+   */
+  result: SimulateCaptureResult;
+}
+```
+
+## SimulateExposureBuildUpOptions
+
+The build-up to render with {@link simulateExposureBuildUp}.
+
+```ts
+export interface SimulateExposureBuildUpOptions {
+  /**
+   * Fractions of `exposure.shutterSeconds` to read out, strictly increasing, each above 0 and at most 1 (1 to 64 of them), for
+   * example `[0.2, 0.4, 0.6, 0.8, 1]`. A fraction of 1 is the whole exposure: `simulateCapture` of the request.
+   */
+  fractions: readonly number[];
+}
+```
+
+## SimulateExposureBuildUpResult
+
+The readouts of {@link simulateExposureBuildUp}, in the order of `fractions`.
+
+```ts
+export interface SimulateExposureBuildUpResult {
+  /** The whole exposure's shutter time, in s. */
+  shutterSeconds: number;
+  frames: readonly SimulateExposureBuildUpFrame[];
+}
+```

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

@@ -9,9 +9,13 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 ```ts
 SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.freeze([
   { id: "lens.catalogue/field-grid", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture"],
-    fast: "#568: the PSF blended over a field grid and tabulated expected electrons, verified per CFA phase against the exact chain",
+    fast: "#568: the PSF blended over a field grid, with each site's expected electrons integrated from its taps' material spectra at use, verified per CFA phase against the exact chain",
     exact: "the environment PSF quadrature with the PSF resolved at each query point", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "fast.lens.catalogue" } },
+  { id: "lens.catalogue/field-grid-cells", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture"],
+    fast: "#603: when the field-grid method runs on a fast request, at least 4 grid cells per field interval (2.20.0's grid), except for the measured lenses of CATALOGUE_FAST_GRID_FULL_ON_SCREEN, whose fallbacks made 4 cells slower",
+    exact: "at least 10 cells per field interval when the field-grid method runs on an exact request (lens.catalogue fast: true with an export or fast: false)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "catalogueFastGridSubdivisions(catalogue!.lensId, fastTop)" }, report: { assumption: "fast.lens.catalogue" } },
   { id: "lens.catalogue/cats-eye", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "#567: with lens.defocus, the lens's bokeh without its cat's eye (the axis kernel everywhere)",
     exact: "the cat's eye shaped at each field point (fast wides and normals)", followsFormatDefault: true,
@@ -21,13 +25,13 @@ SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.fre
     exact: "one zone per site: the PSF at each site centre", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "view.lensPsf" } },
   { id: "lens.diffraction/rolling-shutter-taps", override: "lens.diffraction", methods: "fast-and-exact", runs: ["simulateCapture"],
-    fast: "#565: under rolling-shutter rotation, each PSF tap reads the scene at its own source point",
+    fast: "#565: under rolling-shutter rotation (#551: or subject motion), each PSF tap reads the scene at its own source point",
     exact: "each tap reads the scene at its site-lattice point (ties on chart boundaries resolve as on the lattice)", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction", assumption: "fast.lens.diffraction" } },
-  { id: "output.demosaic.ahd/view-low-signal-correction", override: "output.demosaic", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
-    fast: "(H3) 2048 draws per correction state, applied where a pixel's linear noise exceeds 0.01",
-    exact: "8192 draws per state, at the same 0.01 threshold", followsFormatDefault: true,
-    resolver: { file: CAPTURE, call: "resolveFast(demosaicFast, fastTop)" }, report: { applied: "output.demosaic.ahd", assumption: "view.demosaic" } },
+  { id: "lens.catalogue/rolling-shutter-taps", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture"],
+    fast: "#588: under rolling-shutter rotation, each catalogue PSF tap reads the scene at its own source point",
+    exact: "each tap reads the scene at its site-lattice point (ties on chart boundaries resolve as on the lattice)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "fast.lens.catalogue" } },
   { id: "view.uniform-pixel-sampling", override: "fast", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
     fast: "(H2) a quarter of the samples per axis in display pixels whose pilot finds no detail",
     exact: "the full samples per axis in every display pixel", followsFormatDefault: true,
@@ -37,9 +41,42 @@ SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.fre
     exact: "gpu \"off\": the CPU reference; an explicit gpu wins", followsFormatDefault: true,
     resolver: { file: VIEW, call: "parsePrepareDisplayViewOptions(prepareOptions, (options as { fast?: unknown } | null | undefined)?.fast !== false)" },
     report: { field: "diagnostics.fast.execution" } },
+  { id: "illumination/image-plane-gpu", override: "fast", methods: "fast-and-exact", runs: ["prepareDisplayView"],
+    fast: "#597: gpu \"auto\": an image-plane print under mixed lighting on WebGPU (float32, a bounded approximation): the print's Quality passes light each lattice " +
+      "point per spectral node from the light's spectra and parts (Speed requests too, without site kernels); flagged points resolved on the host",
+    exact: "gpu \"off\": the CPU reference integrates each site from the lit radiance per spectral node in float64; an explicit gpu wins", followsFormatDefault: true,
+    resolver: { file: VIEW, call: "parsePrepareDisplayViewOptions(prepareOptions, (options as { fast?: unknown } | null | undefined)?.fast !== false)" },
+    report: { field: "diagnostics.fast.execution" } },
+  { id: "sensor.spectralStepNanometers", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#590: the default spectral step is 20 nm under any light; under a spiky one (R(20) > 0.01) sensor.spectralSpikiness notes the possible cast",
+    exact: "5 nm under a spiky light, else 20 nm (an explicit sensor.spectralStepNanometers always wins)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "fastTop || !spiky" }, report: { applied: "sensor.spectralStepNanometers", assumption: "sensor.spectralSpikiness" } },
   { id: "sensor.midGrey", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "#535: the mid-gray noise figure is not computed (about 0.3 ms)", exact: "result.sensor.midGrey is computed", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "fastTop ? undefined : 0" }, report: { field: "sensor.midGrey" } },
+  { id: "motion.subject/temporal-midpoints", override: "motion.subject", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#551: with the default count and a still camera, one temporal midpoint per site of the subject's streak plus one, when that is fewer than 8",
+    exact: "the default 8 temporal midpoints (an explicit sensor.temporalSampleCount always wins)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(subjectFast, fastTop)" }, report: { applied: "motion.subject", assumption: "fast.motion.subject" } },
+  { id: "dngImport.warpRectilinear", override: "fast", methods: "fast-and-exact", runs: ["developDngStageImage"],
+    fast: "#600: an imported DNG's WarpRectilinear opcode resampled bilinearly", exact: "cubic convolution (Keys, a = −0.75, the DNG SDK's kernel); default fast unless format names an export", followsFormatDefault: true,
+    resolver: { file: "src/capture/dng-stage-image.ts", call: "resolveFast(options.fast, fastFormatDefault(format, \"capture\"))" }, report: { field: "fast" } },
+  { id: "output.toneCurve/view-luminance-moments", override: "fast", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
+    fast: "#593: a luminance tone curve's moments by an 8-point Gauss–Hermite rule in luminance where its range stays clear of L = 0 (else the full rule)",
+    exact: "a composite 4 × 16-point Gauss–Legendre rule over the luminance's ±8.5σ, split at L = 0", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "rendering: fastTop" }, report: { assumption: "view.rendering" } },
+  { id: "output.highlightMode.reconstruct/view-moments", override: "fast", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
+    fast: "#593, #601: where the reconstruct blend or the desaturation is within reach, the development chain integrated with 6 Gauss–Hermite points per axis (216 nodes)",
+    exact: "16 points per axis (4,096 nodes)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "rendering: fastTop" }, report: { assumption: "view.rendering" } },
+  { id: "prepareDisplayView.gpu/view-coupled-moments", override: "fast", methods: "fast-and-exact", runs: ["prepareDisplayView"],
+    fast: "#593, #601: the WebGPU Speed and Quality kernels' coupled steps with the fast rules (8-point Gauss–Hermite in luminance; 6 points per axis for the chain), float32 within the a-priori bound",
+    exact: "the same kernels with the full rules (4 × 16 Gauss–Legendre; 16 points per axis), fast: false with an explicit gpu", followsFormatDefault: true,
+    resolver: { file: "src/gpu/wgsl-display-view-coupled.ts", call: "out[C.fast] = r.fast ? 1 : 0" }, report: { assumption: "view.rendering" } },
+  { id: "output.highlightMode.reconstruct-neighbors/region-ratios", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#602: each clipped region takes the mean color ratios of the unclipped pixels within 2 pixels of it",
+    exact: "the ratios' harmonic (Laplace) interpolation inward from the region's unclipped neighbors (successive over-relaxation)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "const neighborFast = fastTop" }, report: { assumption: "output.highlightMode.reconstructNeighbors" } },
   { id: "lens.diffraction", override: "lens.diffraction", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "", exact: "the diffraction kernels (a fast method only under rolling-shutter rotation, above)", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction" } },
@@ -49,9 +86,9 @@ SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.fre
   { id: "sensor.pixelAperture.box", override: "sensor.pixelAperture", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "", exact: "the N × N midpoint rule", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "fastInUse" }, report: { applied: "sensor.pixelAperture.box" } },
-  { id: "output.demosaic.ahd", override: "output.demosaic", methods: "exact-only", runs: ["simulateCapture"],
-    fast: "", exact: "the AHD demosaic of the capture (a fast method only in the display view's correction, above)", followsFormatDefault: true,
-    resolver: { file: CAPTURE, call: "resolveFast(demosaicFast, fastTop)" }, report: { applied: "output.demosaic.ahd" } }
+  { id: "output.demosaic.ahd", override: "output.demosaic", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "", exact: "the AHD demosaic of the capture; in the display view, AHD's two linear candidates and its choice on the noise-free mosaic (2.22.0: no low-signal correction, so no fast method)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "[\"output.demosaic.ahd\", ahd, demosaicFast]" }, report: { applied: "output.demosaic.ahd" } }
 ] as const satisfies readonly SimulateCaptureFastMethod[])
 ```
 
@@ -71,7 +108,7 @@ export interface SimulateCaptureFastMethod {
   /** "fast-and-exact": both methods exist; "exact-only": the record takes `fast`, but there is no fast method yet (reports false). */
   methods: "fast-and-exact" | "exact-only";
   /** Where it applies. */
-  runs: readonly ("simulateCapture" | "simulateDisplayView" | "prepareDisplayView")[];
+  runs: readonly ("simulateCapture" | "simulateDisplayView" | "prepareDisplayView" | "developDngStageImage")[];
   /** The fast method and the exact one, in words (empty for exact-only). */
   fast: string;
   exact: string;

package/docs/api/facade-image-plane-enable.md

@@ -0,0 +1,16 @@
+# facade/image-plane-enable.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## prepareImagePlaneScenes
+
+2.21 (#581): enables `{ kind: "image-plane" }` scenes (a photo as a flat print, docs/IMAGE_PLANE.md) in this JavaScript realm by
+loading their module (a lazy chunk of about 14 KB gzip with its lattice data). Call it once, in the worker that captures, before
+the first request with such a scene; later calls resolve at once. A request with an image-plane scene before it fails with a
+message saying so.
+
+```ts
+export async function prepareImagePlaneScenes(): Promise<void>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-mixed-illumination.md

@@ -0,0 +1,67 @@
+# facade/mixed-illumination.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## MixedIllumination
+
+2.22 (#550), `simulateCapture` `illumination`: sources blended across the chart and point sources with inverse-square falloff
+(docs/MIXED_ILLUMINATION.md). It replaces `illuminant` and `illuminanceLux`. `sources` lists 1 to 8 sources (with two or more, a
+`blend` is required; one lights the whole plane); `points` lists 1 to 8 point sources; a request needs two or more sources or at least one point. Blend
+coordinates are chart-local with `chartSize` and frame units without it; (0, 0) is the frame center.
+
+```ts
+export interface MixedIllumination {
+  sources?: readonly MixedIlluminationSource[];
+  blend?: MixedIlluminationBlend;
+  points?: readonly MixedIlluminationPointSource[];
+}
+```
+
+## MixedIlluminationBlend
+
+How the sources blend across the chart. `linear-gradient` and `radial` map a point to a position t in [0, 1] (its projection
+onto `from` → `to`, clamped; or its distance from `center` over `radius`, clamped) and crossfade linearly between consecutive
+sources at their `stops` (one per source, non-decreasing in [0, 1]; default evenly spaced from 0 to 1): source 0 alone up to
+stops[0], the last source alone from its stop on, and two equal stops a hard edge (the later source from the stop on).
+`regions` gives each point the source of the first rectangle that contains it (bounds inclusive) and `outsideSource` elsewhere.
+
+```ts
+export type MixedIlluminationBlend =
+  | { kind: "linear-gradient"; from: MixedIlluminationPoint; to: MixedIlluminationPoint; stops?: readonly number[] }
+  | { kind: "radial"; center?: MixedIlluminationPoint; radius: number; stops?: readonly number[] }
+  | { kind: "regions"; regions: readonly { source: number; uMin: number; uMax: number; vMin: number; vMax: number }[]; outsideSource: number };
+```
+
+## MixedIlluminationPoint
+
+A point in chart coordinates (see {@link MixedIllumination}).
+
+```ts
+export interface MixedIlluminationPoint { u: number; v: number }
+```
+
+## MixedIlluminationPointSource
+
+2.22 (#550): a point light on the scene plane's front side: an illuminant spectrum, a position in metres (`xM`, `yM` on the plane
+from the optical axis, +x right and +y up as seen from the camera; `heightM` > 0 in front of the plane, toward the camera) and an
+intensity, either in candela or as the illuminance it gives at normal incidence at a reference distance (I = E·r²).
+
+```ts
+export interface MixedIlluminationPointSource {
+  illuminant: CaptureIlluminant;
+  position: { xM: number; yM: number; heightM: number };
+  intensity: { candela: number } | { illuminanceLux: number; distanceM: number };
+}
+```
+
+## MixedIlluminationSource
+
+One light source of a mixed illumination: an illuminant (as `simulateCapture` `illuminant` takes it) at an illuminance.
+
+```ts
+export interface MixedIlluminationSource {
+  illuminant: CaptureIlluminant;
+  /** Illuminance this source alone gives where its weight is 1, lux, (0, 1e7]. */
+  illuminanceLux: number;
+}
+```

package/docs/api/facade-quality-paths.md

@@ -0,0 +1,24 @@
+# facade/quality-paths.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## prepareQualityPaths
+
+Loads the engine's on-demand full-quality code now instead of at the first request that needs it (#594): the CPU Quality kit
+(diffraction, the capture's AHD demosaic, `lens.defocus` beyond the geometric disc, the image-space provider of lens projection,
+distortion and vignetting, the display view's coupled tone, reconstruct and desaturation steps, the neighbor highlight
+reconstruction), the opt-in kit (`sensor.profile`, `illumination`, `motion.subject`) and the display view's GPU full-quality code
+(the Quality passes behind `prepareDisplayView(…, { gpu: "auto" | "require" })`), together with the GPU session it builds on.
+
+Optional: without it, the first request that needs the code loads it. Safe to call at any time and from any number of places:
+concurrent calls share one load, and a call after it loaded resolves at once and loads nothing. It changes no result. If the
+load fails (for example a chunk download error) the promise rejects with `ImageKernelExecutionError` reason
+`quality-code-unavailable`; nothing is remembered, so a later call or request tries again, and a render in the meantime runs
+the CPU reference, labelled with that reason. A bundler that splits dynamic imports keeps this code out of the first load
+whether or not this function is imported.
+
+```ts
+export function prepareQualityPaths(): Promise<void>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-representative-light-sources.md

@@ -0,0 +1,131 @@
+# facade/representative-light-sources.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createRepresentativeLightSourceIlluminant
+
+A capture illuminant for a source: `{ kind: "spectrum", spectrum, label }` with the spectrum of
+{@link createRepresentativeLightSourceSpectrum} and the label "<name> (representative, not a named product)".
+
+```ts
+export function createRepresentativeLightSourceIlluminant(input: { sourceId: RepresentativeLightSourceId }): Extract<CaptureIlluminant, { kind: "spectrum" }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createRepresentativeLightSourceSpectrum
+
+A source's relative spectral power distribution S(λ) = b + Σ aₖ·exp(−½((λ − μₖ)/σₖ)²) as a function spectrum on
+360–830 nm (relative units; values memoized per wavelength). Pass it to a capture as
+`illuminant: { kind: "spectrum", spectrum }`; for color work use `sensor.spectralStepNanometers: 5` or finer
+(docs/LIGHT_SOURCES.md, "Quadrature"). Throws `InvalidScientificInputError` outside 360–830 nm.
+
+```ts
+export function createRepresentativeLightSourceSpectrum(input: { sourceId: RepresentativeLightSourceId }): ColorimetricSpectrum;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## getRepresentativeLightSourceSet
+
+The built-in representative light sources: Photivra's own parametric spectra of a tri-phosphor fluorescent tube and
+three white LEDs (low and high color rendering at 4000 K, warm at 2700 K). A static, deeply frozen engine contract.
+Each is "representative, not a named product"; docs/LIGHT_SOURCES.md gives every formula and the reasons for it.
+
+```ts
+export function getRepresentativeLightSourceSet(): RepresentativeLightSourceSet;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## REPRESENTATIVE_LIGHT_SOURCE_IDS
+
+The source ids, in set order.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_IDS = Object.freeze([
+  "tri-phosphor-fluorescent-4000k", "white-led-low-rendering-4000k", "white-led-high-rendering-4000k", "warm-white-led-2700k"
+] as const)
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_SET_ID
+
+Identity of the built-in light-source set.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_SET_ID = "photivra-representative-light-sources"
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION
+
+Version of the set's spectra; a change to any spectrum changes it.
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION = "1.0.0"
+```
+
+## REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS
+
+Domain of every spectrum, nm (the CIE 1931 observer's domain; the capture facade uses 380–780 nm of it).
+
+```ts
+REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS = Object.freeze({ minimum: 360, maximum: 830 })
+```
+
+## RepresentativeLightSource
+
+One built-in source: its id, name, design reason and spectrum definition.
+
+```ts
+export interface RepresentativeLightSource {
+  sourceId: RepresentativeLightSourceId;
+  /** Photivra's descriptive name, for example "White LED, high color rendering, 4000 K". */
+  name: string;
+  family: "fluorescent" | "led";
+  /** The CCT the spectrum was designed for, K (its computed CCT is within 1 K of it, Duv within 0.0001; docs/LIGHT_SOURCES.md). */
+  nominalCorrelatedColorTemperatureKelvin: number;
+  /** Always "representative, not a named product". */
+  label: "representative, not a named product";
+  /** One sentence: what the source represents and why it is built this way. */
+  reason: string;
+  /** The constant b (a low continuum), relative units. */
+  base: number;
+  bands: readonly RepresentativeLightSourceBand[];
+}
+```
+
+## RepresentativeLightSourceBand
+
+One Gaussian band a·exp(−½((λ − μ)/σ)²) of a source spectrum.
+
+```ts
+export interface RepresentativeLightSourceBand {
+  kind: "gaussian";
+  /** What the band represents, for example "blue pump" or "green phosphor line". */
+  role: string;
+  amplitude: number;
+  centerNanometers: number;
+  standardDeviationNanometers: number;
+}
+```
+
+## RepresentativeLightSourceId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type RepresentativeLightSourceId = (typeof REPRESENTATIVE_LIGHT_SOURCE_IDS)[number];
+```
+
+## RepresentativeLightSourceSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RepresentativeLightSourceSet {
+  setId: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_ID;
+  setVersion: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION;
+  wavelengthRangeNanometers: { readonly minimum: number; readonly maximum: number };
+  sources: readonly RepresentativeLightSource[];
+}
+```

package/docs/api/facade-scene-radiance.md

@@ -91,7 +91,8 @@ provider `providerProfileId`.
 
 ```ts
 export function createPlanarSceneRadianceProvider(input: {
-  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  /** An `image-plane` scene (#581) is refused: it is taken by the facade's capture and display-view functions, which load its module. */
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   distanceM: number;
@@ -110,6 +111,47 @@ export function createPlanarSceneRadianceProvider(input: {
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ImagePlaneImage
+
+2.21 (#581): an image the caller supplies, for an {@link ImagePlaneScene}. `data` holds `width × height` pixels row by row
+from the top, `channels` (3: RGB, 4: RGBA) samples each, in the encoding's type: `srgb-8` Uint8Array or Uint8ClampedArray
+(canvas `ImageData.data`), `srgb-16` Uint16Array, `linear-srgb` Float32Array. sRGB primaries and white (IEC 61966-2-1) in
+every encoding; `srgb-8` and `srgb-16` are decoded with the sRGB transfer function, `linear-srgb` is already linear and is
+clipped to [0, 1] (the clipped samples are counted). Alpha is linear coverage over the paper. The array is read, never
+changed or kept beyond the call.
+
+```ts
+export interface ImagePlaneImage {
+  width: number;
+  height: number;
+  channels: 3 | 4;
+  encoding: "srgb-8" | "srgb-16" | "linear-srgb";
+  data: Uint8Array | Uint8ClampedArray | Uint16Array | Float32Array;
+}
+```
+
+## ImagePlaneScene
+
+2.21 (#581): a photo as a flat matte print on the scene plane, lit by the request's illuminant like a chart. Each pixel's
+color becomes a reflectance spectrum through the engine's print reflectance lattice (docs/IMAGE_PLANE.md): an
+approximation, a print of an image that was already processed, clipped and blurred by the camera that took it. The print's
+physical size is `chartSize` (its height defaults to the image's aspect); without it the print is fitted inside the frame,
+centered, on the 18 % surround.
+
+```ts
+export interface ImagePlaneScene {
+  kind: "image-plane";
+  sceneId: string;
+  image: ImagePlaneImage;
+  /** The paper and the deepest ink: reflectances of sRGB white and black, 0 ≤ black < white ≤ 1. Defaults 0.90 and 0.01. */
+  paper?: { whiteReflectance?: number; blackReflectance?: number };
+  /** How the print is reconstructed between pixel centers. Default `bilinear` (the pixels' spectra, bilinearly weighted). */
+  interpolation?: "bilinear" | "nearest";
+  /** Opt-in raised pixel limit: an integer up to the full-resolution ceiling. Default 24 000 000 pixels. */
+  maximumPixels?: number;
+}
+```
+
 ## PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W
 
 CIE maximum luminous efficacy for photopic vision, lm/W.
@@ -128,8 +170,11 @@ export interface PlanarSceneRadianceProvider {
   providerProfileId: string;
   evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult;
   evaluateApertureRadiance(request: Readonly<SceneRadianceEvaluationRequest>, ray: Readonly<SensorApertureRay>): SceneRadianceEvaluationResult;
-  /** Spectral radiance at a plane point (frame units), the same value the callbacks return. */
-  radianceAt(u: number, v: number, wavelengthNanometers: number): number;
+  /**
+   * Spectral radiance at a plane point (frame units), the same value the callbacks return. #551: a moving subject's provider
+   * reads it at time `t` (seconds from the first opening, default 0); a still scene ignores it.
+   */
+  radianceAt(u: number, v: number, wavelengthNanometers: number, t?: number): number;
   /**
    * 2.3, chart scenes only: the chart material at a plane point (frame units), or `materials.length` for the
    * surround of a fixed-size chart; `materialRadiance` gives that material's spectral radiance, the same value
@@ -137,6 +182,12 @@ export interface PlanarSceneRadianceProvider {
    */
   chartMaterialAt?(u: number, v: number): number;
   materialRadiance?(material: number, wavelengthNanometers: number): number;
+  /**
+   * 2.21 (#581), image-plane scenes only: the tabulated expected signal's scene at these spectral nodes and channel responses, its
+   * radiance per node and, for the direct path, Σ_n A_c(λ_n)·L(λ_n) integrated from each pixel's reconstructed spectrum
+   * (`ResolvedImagePlaneScene.pixelSignals`, the surround's reflectance times the neutral signal outside the print).
+   */
+  imageSignalScene?(wavelengths: readonly number[], perNode: readonly Float64Array[]): ImagePlaneSignalScene | ImagePlaneLitScene;
 }
 ```