@photivra/engine 2.19.0 → 2.21.0

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

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

package/docs/api/facade-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-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;
 }
 ```