@photivra/engine 2.20.0 → 2.21.0

package/docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # Public API reference
 
-Generated from the exact root exports for **@photivra/engine 2.20.0 / root contract 2.20.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
+Generated from the exact root exports for **@photivra/engine 2.21.0 / root contract 2.21.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
 
 Use [the developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md) for executable paths and scientific boundaries. Types are contracts, not runtime validation: parse untrusted data, preserve units/reference frames, read assessment blockers, and retain evidence/limitations. Optional properties do not imply a universal default. Model/schema IDs remain independent of the distribution.
 
@@ -976,6 +976,26 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`GenericReleaseDriveMode`](api/equipment-release-capabilities.md#genericreleasedrivemode) | Type |
 | [`parseGenericReleaseCapabilityProfile`](api/equipment-release-capabilities.md#parsegenericreleasecapabilityprofile) | Runtime |
 
+## equipment/sensor-profile-body.ts
+
+[Detailed contracts](api/equipment-sensor-profile-body.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/equipment/sensor-profile-body.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`SENSOR_PROFILE_ISO_ANCHOR`](api/equipment-sensor-profile-body.md#sensor_profile_iso_anchor) | Runtime |
+| [`SensorProfile`](api/equipment-sensor-profile-body.md#sensorprofile) | Type |
+| [`SensorProfileValueKind`](api/equipment-sensor-profile-body.md#sensorprofilevaluekind) | Type |
+
+## equipment/sensor-profiles.ts
+
+[Detailed contracts](api/equipment-sensor-profiles.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/equipment/sensor-profiles.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`resolveSensorProfile`](api/equipment-sensor-profiles.md#resolvesensorprofile) | Runtime |
+| [`SENSOR_PROFILE_IDS`](api/equipment-sensor-profiles.md#sensor_profile_ids) | Runtime |
+| [`SENSOR_PROFILES`](api/equipment-sensor-profiles.md#sensor_profiles) | Runtime |
+
 ## exposure/auto-iso-slowest-shutter.ts
 
 [Detailed contracts](api/exposure-auto-iso-slowest-shutter.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/exposure/auto-iso-slowest-shutter.ts)
@@ -1314,6 +1334,19 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`DisplayViewCorrectionStateSet`](api/facade-display-view.md#displayviewcorrectionstateset) | Type |
 | [`serializeDisplayViewCorrectionStates`](api/facade-display-view.md#serializedisplayviewcorrectionstates) | Runtime |
 
+## facade/exposure-build-up.ts
+
+[Detailed contracts](api/facade-exposure-build-up.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/exposure-build-up.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS`](api/facade-exposure-build-up.md#exposure_build_up_maximum_fractions) | Runtime |
+| [`EXPOSURE_BUILD_UP_STREAM_BASE`](api/facade-exposure-build-up.md#exposure_build_up_stream_base) | Runtime |
+| [`simulateExposureBuildUp`](api/facade-exposure-build-up.md#simulateexposurebuildup) | Runtime |
+| [`SimulateExposureBuildUpFrame`](api/facade-exposure-build-up.md#simulateexposurebuildupframe) | Type |
+| [`SimulateExposureBuildUpOptions`](api/facade-exposure-build-up.md#simulateexposurebuildupoptions) | Type |
+| [`SimulateExposureBuildUpResult`](api/facade-exposure-build-up.md#simulateexposurebuildupresult) | Type |
+
 ## facade/fast-methods.ts
 
 [Detailed contracts](api/facade-fast-methods.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/fast-methods.ts)
@@ -1323,6 +1356,44 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`SIMULATE_CAPTURE_FAST_METHODS`](api/facade-fast-methods.md#simulate_capture_fast_methods) | Runtime |
 | [`SimulateCaptureFastMethod`](api/facade-fast-methods.md#simulatecapturefastmethod) | Type |
 
+## facade/image-plane-enable.ts
+
+[Detailed contracts](api/facade-image-plane-enable.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/image-plane-enable.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`prepareImagePlaneScenes`](api/facade-image-plane-enable.md#prepareimageplanescenes) | Runtime |
+
+## facade/mixed-illumination.ts
+
+[Detailed contracts](api/facade-mixed-illumination.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/mixed-illumination.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`MixedIllumination`](api/facade-mixed-illumination.md#mixedillumination) | Type |
+| [`MixedIlluminationBlend`](api/facade-mixed-illumination.md#mixedilluminationblend) | Type |
+| [`MixedIlluminationPoint`](api/facade-mixed-illumination.md#mixedilluminationpoint) | Type |
+| [`MixedIlluminationPointSource`](api/facade-mixed-illumination.md#mixedilluminationpointsource) | Type |
+| [`MixedIlluminationSource`](api/facade-mixed-illumination.md#mixedilluminationsource) | Type |
+
+## facade/representative-light-sources.ts
+
+[Detailed contracts](api/facade-representative-light-sources.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/representative-light-sources.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`createRepresentativeLightSourceIlluminant`](api/facade-representative-light-sources.md#createrepresentativelightsourceilluminant) | Runtime |
+| [`createRepresentativeLightSourceSpectrum`](api/facade-representative-light-sources.md#createrepresentativelightsourcespectrum) | Runtime |
+| [`getRepresentativeLightSourceSet`](api/facade-representative-light-sources.md#getrepresentativelightsourceset) | Runtime |
+| [`REPRESENTATIVE_LIGHT_SOURCE_IDS`](api/facade-representative-light-sources.md#representative_light_source_ids) | Runtime |
+| [`REPRESENTATIVE_LIGHT_SOURCE_SET_ID`](api/facade-representative-light-sources.md#representative_light_source_set_id) | Runtime |
+| [`REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION`](api/facade-representative-light-sources.md#representative_light_source_set_version) | Runtime |
+| [`REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS`](api/facade-representative-light-sources.md#representative_light_source_wavelength_range_nanometers) | Runtime |
+| [`RepresentativeLightSource`](api/facade-representative-light-sources.md#representativelightsource) | Type |
+| [`RepresentativeLightSourceBand`](api/facade-representative-light-sources.md#representativelightsourceband) | Type |
+| [`RepresentativeLightSourceId`](api/facade-representative-light-sources.md#representativelightsourceid) | Type |
+| [`RepresentativeLightSourceSet`](api/facade-representative-light-sources.md#representativelightsourceset) | Type |
+
 ## facade/scene-radiance.ts
 
 [Detailed contracts](api/facade-scene-radiance.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/scene-radiance.ts)
@@ -1337,6 +1408,8 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`CHART_SIZE_DEFAULT_SURROUND_REFLECTANCE`](api/facade-scene-radiance.md#chart_size_default_surround_reflectance) | Runtime |
 | [`ChartSizeOption`](api/facade-scene-radiance.md#chartsizeoption) | Type |
 | [`createPlanarSceneRadianceProvider`](api/facade-scene-radiance.md#createplanarsceneradianceprovider) | Runtime |
+| [`ImagePlaneImage`](api/facade-scene-radiance.md#imageplaneimage) | Type |
+| [`ImagePlaneScene`](api/facade-scene-radiance.md#imageplanescene) | Type |
 | [`PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W`](api/facade-scene-radiance.md#photopic_maximum_luminous_efficacy_lm_per_w) | Runtime |
 | [`PlanarSceneRadianceProvider`](api/facade-scene-radiance.md#planarsceneradianceprovider) | Type |
 | [`resolveCaptureIlluminant`](api/facade-scene-radiance.md#resolvecaptureilluminant) | Runtime |
@@ -1563,6 +1636,14 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`CalculateProjectedMotionBlurInput`](api/motion-projected-motion.md#calculateprojectedmotionblurinput) | Type |
 | [`ProjectedMotionBlur`](api/motion-projected-motion.md#projectedmotionblur) | Type |
 
+## motion/subject-motion.ts
+
+[Detailed contracts](api/motion-subject-motion.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/motion/subject-motion.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`SimulateCaptureSubjectMotion`](api/motion-subject-motion.md#simulatecapturesubjectmotion) | Type |
+
 ## motion/temporal-exposure-sum.ts
 
 [Detailed contracts](api/motion-temporal-exposure-sum.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/motion/temporal-exposure-sum.ts)
@@ -1801,6 +1882,17 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`resolveFrontOfLensFilterTransmission`](api/optics-front-of-lens-filter.md#resolvefrontoflensfiltertransmission) | Runtime |
 | [`ResolveFrontOfLensFilterTransmissionInput`](api/optics-front-of-lens-filter.md#resolvefrontoflensfiltertransmissioninput) | Type |
 
+## optics/generic-lens-lateral-color.ts
+
+[Detailed contracts](api/optics-generic-lens-lateral-color.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/optics/generic-lens-lateral-color.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`calculateLateralColorFringe`](api/optics-generic-lens-lateral-color.md#calculatelateralcolorfringe) | Runtime |
+| [`CalculateLateralColorFringeInput`](api/optics-generic-lens-lateral-color.md#calculatelateralcolorfringeinput) | Type |
+| [`LateralColorDisplacement`](api/optics-generic-lens-lateral-color.md#lateralcolordisplacement) | Type |
+| [`LateralColorFringe`](api/optics-generic-lens-lateral-color.md#lateralcolorfringe) | Type |
+
 ## optics/generic-nd-filter-presets.ts
 
 [Detailed contracts](api/optics-generic-nd-filter-presets.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/optics/generic-nd-filter-presets.ts)
@@ -2183,6 +2275,7 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 
 | Export | Kind |
 | --- | --- |
+| [`ChannelDispersion`](api/output-developed-lens-corrections.md#channeldispersion) | Type |
 | [`GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM`](api/output-developed-lens-corrections.md#generic_lens_correction_channel_wavelengths_nm) | Runtime |
 
 ## output/generic-lens-corrections.ts
@@ -2191,6 +2284,8 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 
 | Export | Kind |
 | --- | --- |
+| [`calculateChannelEffectiveDispersion`](api/output-generic-lens-corrections.md#calculatechanneleffectivedispersion) | Runtime |
+| [`CalculateChannelEffectiveDispersionInput`](api/output-generic-lens-corrections.md#calculatechanneleffectivedispersioninput) | Type |
 | [`createGenericLensCorrectionProfile`](api/output-generic-lens-corrections.md#creategenericlenscorrectionprofile) | Runtime |
 | [`CreateGenericLensCorrectionProfileInput`](api/output-generic-lens-corrections.md#creategenericlenscorrectionprofileinput) | Type |
 
@@ -2336,7 +2431,9 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`calculatePrintPlan`](api/output-print-plan.md#calculateprintplan) | Runtime |
 | [`calculatePrintSizeLimit`](api/output-print-plan.md#calculateprintsizelimit) | Runtime |
 | [`parsePrintPlanInput`](api/output-print-plan.md#parseprintplaninput) | Runtime |
+| [`PrintContainLayout`](api/output-print-plan.md#printcontainlayout) | Type |
 | [`PrintedImageSize`](api/output-print-plan.md#printedimagesize) | Type |
+| [`PrintFit`](api/output-print-plan.md#printfit) | Type |
 | [`PrintLength`](api/output-print-plan.md#printlength) | Type |
 | [`PrintNativeSource`](api/output-print-plan.md#printnativesource) | Type |
 | [`PrintPlan`](api/output-print-plan.md#printplan) | Type |

package/docs/QUICK_START.md

@@ -88,6 +88,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `chartSize` | fill the frame | 2.3: `{ widthM, heightM?, surroundReflectance? }` places the chart at its physical size (see [Fixed-size chart](#fixed-size-chart-23)). |
 | `illuminant` | Planckian 6500 K | Also `"cie-a"`, `{ kind: "planckian", temperatureKelvin }`, `{ kind: "daylight", correlatedColorTemperatureKelvin, basis }` or `{ kind: "spectrum", spectrum }`. |
 | `illuminanceLux` | 21 481 (π·80 000/11.7) | See [Exposure](#exposure). |
+| `illumination` | off | 2.22 (#550): mixed lighting, two to eight sources (`{ illuminant, illuminanceLux }`) blended across the chart by a linear gradient, a radial falloff or regions, and point sources (`points`) with inverse-square falloff, instead of `illuminant` and `illuminanceLux`. The frame center's light sets the grey card and its strongest source the `"scene-illuminant"` white balance (see [Mixed lighting](https://github.com/Photivra/photivra/blob/main/docs/MIXED_ILLUMINATION.md)). |
 | `output.width`, `output.height` | 64 × 64 | Output pixels, 1–4094 each. The sensor has one extra site on each side for demosaicing (see `output.borderHandling`). |
 | `output.maximumPixels` | off | Opt-in large images (2.2): the most native sensor sites the capture may allocate, up to `NATIVE_RAW_LIMITS.ceilingPixels` (2^27). Sides may then reach 16 384 sites including the margin (see [Large images](#large-images)). |
 | `output.region` | whole frame | 2.3: `{ x, y, width, height }` renders that rectangle of the frame, byte-identical to the whole render (see [Region rendering](#region-rendering-23)). |
@@ -118,6 +119,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `motion.angularVelocityRadPerSec` | still | `{ pitch?, yaw?, roll? }` in rad/s (see [Motion](#motion)). |
 | `motion.shutter` | `"global"` | Or `"rolling"`. |
 | `motion.rollingShutterSkewSeconds` | the body's readout skew | Rolling only. |
+| `motion.subject` | still subject | 2.22.0: `{ velocityMPerSec?: { x?, y? }, angularVelocityRadPerSec?, region?, fast? }`, a moving subject (see [Subject motion](#subject-motion)). |
 | `signal`, `onProgress` | none | An `AbortSignal` cancels the running task; `onProgress` reports `raw`, `white-balance`, `development`, `diffraction-correction` and `sharpening` (#571: output rows, with those options) and `jpeg` tiles. The last event of each stage has `completedTileCount === totalTileCount`. The capture yields to the host about every 8 ms with a `MessageChannel` message (else `setImmediate`, else `setTimeout`), so other queued tasks run in between: an abort sent from another task, such as a Web Worker `message` event, takes effect at the next yield. |
 
 Unknown fields are rejected, so a typo never silently falls back to a default.
@@ -530,6 +532,29 @@ SNR is 88.5 (38.9 dB); at ISO 6400 with 1/64 of the light, S ≈ 123 e⁻ and th
 the photon shot noise grows as √S, so less light means more noise whatever the ISO. The display view
 reports the same `sensor` record as its capture.
 
+### Sensor profiles (#554)
+
+`sensor.profile` takes one of eight representative sensor profile records whose values come from
+published specifications (`SENSOR_PROFILES`, or `resolveSensorProfile(id)`; unnamed, by format,
+resolution, architecture and era), checked strictly, so a modified copy also works. It
+replaces the body's ISO range, readout regimes (full well, read noise of each conversion gain, the
+dual-gain switch and the high gain's storage, ADC bit depth), readout time and fixed-pattern noise,
+and sets the default pitch and peak QE; the characteristics above still override it one at a time.
+
+```ts
+import { resolveSensorProfile, simulateCapture } from "@photivra/engine";
+const phone = await simulateCapture({ scene: { preset: "uniform" }, sensor: { profile: resolveSensorProfile("phone-50mp-stacked") } });
+phone.sensor.fullWellElectrons;   // 8 600 e⁻ at 1.197 µm
+```
+
+Each profile's base ISO is re-rated from its full well, QE and pixel area, so the same ISO reaches
+the RAW white at the same exposure on every profile (the assumption `sensor.profile` records the
+values and the rounding). The phone profile takes the catalogue's three phone lenses
+(`lens: { catalogue: "pv-24-1.8-phone" }`), and they need it. With a profile, a catalogue lens is framed on
+the profile's real sensor (the largest centred region of the output's aspect; assumption `sensor.profileView`), so it
+shows its real field of view. Values, sources, the framing and the ISO rating:
+[SENSOR_PROFILES.md](https://github.com/Photivra/photivra/blob/main/docs/SENSOR_PROFILES.md).
+
 ## Exposure
 
 The facade meters the scene like a reflected-light meter:
@@ -1689,6 +1714,48 @@ const pan = await simulateCapture({
 console.log(pan.assumptions.find((a) => a.id === "sensor.shutter")?.value, pan.exposure.settings.shutterSeconds);
 ```
 
+## Subject motion
+
+`motion.subject` (2.22.0, #551) moves the subject on the scene plane during the exposure: the whole scene, or one
+rectangle of it (`region: { centerXM, centerYM, widthM, heightM }` in metres at rest) over a still background.
+
+- `velocityMPerSec: { x, y }` is a translation in m/s on the plane (+x right, +y up as seen from the camera).
+  `angularVelocityRadPerSec` adds a rotation about an axis parallel to the optical axis, counter-clockwise as seen from
+  the camera: the optical axis for the whole scene, the region's center for a region.
+- The model is rigid motion of a planar layer. At time t from the first opening (camera rotation's time reference), a
+  subject point at rest q is at R(ωt)(q − c) + c + v·t. A plane point shows the subject where one is there, else the
+  region's rest rectangle shows a neutral 18 % background (what the subject revealed), else the still scene. The background
+  is lit by the plane's irradiance at that point: the illuminant, or with `illumination` (#550) the blend and point sources there.
+- Every scene query reads the subject at its own time. The blur is therefore the same temporal midpoint quadrature as
+  camera rotation (`sensor.temporalSampleCount`, default 8 with a moving subject), and an edge streaks over
+  v·T·m on the sensor (m = v′/D, the thin-lens image distance over the subject distance). With few samples a long streak
+  shows separate copies; raise the count. A test checks the length within sampling error.
+- A rolling shutter skews a moving subject: each row's exposure window opens later, so it sees the subject later. A test
+  checks the skew against the site windows' start offsets.
+- Panning: a camera yaw of −v/D rad/s (the engine's rotation convention) follows a subject moving at v m/s in +x. The
+  subject stays sharp and the background streaks.
+- It combines with `lens.diffraction`, `lens.defocus` (global shutter; their site lattices are formed at each midpoint), the
+  lens projection, distortion and vignetting, and camera rotation. `lens.pupilSampling` is refused.
+- Display view: sideways motion under a global shutter only. It refuses a rotating subject and a rolling shutter with a
+  reason; `simulateCapture` renders both.
+- Fast method (2.20.0 convention): with the default count and a still camera, `fast` takes one midpoint per site of the
+  streak plus one when that is fewer than 8 (taps less than one site apart). Exact keeps 8, and an explicit
+  `sensor.temporalSampleCount` always wins. Fast is the default for sRGB samples and the display view, exact for DNG,
+  JPEG and PNG.
+- Off by default: a request without `motion.subject` is byte-identical to 2.20.0.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+// A subject 4 mm wide moving right at 0.2 m/s, with the camera panning to follow it.
+const pan = await simulateCapture({
+  scene: { preset: "bar-groups" }, subjectDistanceM: 2, lens: { focalLengthMm: 50 },
+  motion: { angularVelocityRadPerSec: { yaw: -0.1 }, subject: { velocityMPerSec: { x: 0.2 }, region: { centerXM: 0.002, centerYM: 0, widthM: 0.004, heightM: 0.004 } } },
+  output: { width: 32, height: 16 }
+});
+console.log(pan.assumptions.find((a) => a.id === "motion.subject")?.value);
+```
+
 ## Performance
 
 Almost all of the cost is engine time per sensor site; the facade itself adds little. Since 2.0, the
@@ -2029,6 +2096,64 @@ developed image in 64-bit floats (24 bytes per pixel, 549 MiB at 24 MP), held as
 sampled every 50 ms). The extra pass therefore costs about 5 s on one worker after the parts, against about 10 s to render
 the whole frame again on one worker.
 
+### Exposure build-up (#534)
+
+`simulateExposureBuildUp(options, { fractions })` renders fractions of one exposure as one accumulating process, the way a
+camera's live readout of a long exposure shows the light building up. Each fraction is read out and developed as its own
+photo, and the fraction at 1 is `simulateCapture(options)`, byte for byte (owner decision, 2026-11-06).
+
+- **Signal.** Each fraction fⱼ below 1 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. That includes camera rotation, `motion.subject` (#551), mixed lighting (#550, which does not
+  change over time) and, with a rolling shutter, each row's own window. No per-channel signal is precomputed (owner rule).
+- **Charge.** Photon and dark-charge arrivals are Poisson processes with any rate over time. Given a count n over [0, t], the
+  count over [0, s] is Binomial(n, Λ(s)/Λ(t)), with Λ the expected count (R. G. Gallager, *Discrete Stochastic Processes*,
+  chapter 2, sections 2.4 and 2.5, MIT OpenCourseWare 6.262, free). The whole exposure keeps its ordinary draws. Going down
+  the fractions, each site's photo and dark counts are split: N(fⱼ) ~ Binomial(N(fⱼ₊₁), λ(fⱼ)/λ(fⱼ₊₁)), with λ the site's
+  expected mean in each render (after PRNU and DSNU). As a result:
+  - each fraction's counts are Poisson with that fraction's own mean, which is the mean and variance of a capture at fⱼ·t;
+  - the counts never decrease from one fraction to the next;
+  - two fractions' counts covary by the earlier one's mean.
+
+  The binomial draws are exact: inversion, and Hörmann's BTRS rejection (`src/sensor/binomial-sample.ts`).
+- **Quadrature.** The windows are nested, so the true means never decrease. The temporal midpoint quadrature can still give an
+  earlier fraction a larger estimate than a later one at a site under motion. There the count is kept (probability 1), and the
+  `exposure.buildUp` assumption counts those sites (`nonMonotoneSites`). Raise `sensor.temporalSampleCount` to remove them.
+- **Sensor.** Fixed-pattern noise (PRNU, DSNU, hot pixels, offsets) belongs to the sensor and is the same in every fraction.
+  Each fraction's charge is clipped at the full well (`sensor.fullWell`), then read out once: its own read noise (the regime's
+  components; dual gain as the ISO selects), pre-ADC and ADC saturation, and quantization at the ADC bit depth (#555; a #554
+  sensor profile's readout feeds the same stage).
+- **Cost and settings.** One capture per fraction, plus about 64 bytes per native site for the chain. The request's `fast`
+  and the format default apply to every fraction, and the build-up adds no fast method: with `fast: false` (the calculator's
+  setting) every fraction is an exact capture. `"auto"` white balance is measured on each fraction, as its own photo.
+- **Limits.** On screen only: formats `"srgb-8"` and `"srgb-16"` (a fraction's JPEG, PNG or DNG is refused). 1 to 64
+  fractions, strictly increasing, above 0 and at most 1. Each fraction's shutter fⱼ·t must be one the body can set. A
+  fraction's realization depends on the whole list, because each step of the chain has its own seeded streams
+  (`EXPOSURE_BUILD_UP_STREAM_BASE`). The same request and list always give the same frames.
+- **Result.** One frame per fraction: `{ fraction, elapsedSeconds, result }`. Below 1, `result` is the fraction capture's
+  result (`image`, `raw`, `plan` and `request` at fⱼ·t), with the build-up's counts and the assumption `exposure.buildUp`.
+  Its `exposure` and `sensor` are the whole exposure's reports: the camera's settings and noise figure, not the elapsed part's.
+
+```ts
+import { simulateExposureBuildUp } from "@photivra/engine";
+
+const build = await simulateExposureBuildUp({ scene: { preset: "slanted-edge" }, exposure: { mode: "manual", shutterSeconds: 1 / 15, iso: 400 },
+  motion: { angularVelocityRadPerSec: { yaw: 0.2 } }, output: { width: 64, height: 48 } }, { fractions: [0.2, 0.4, 0.6, 0.8, 1] });
+for (const frame of build.frames) console.log(frame.fraction, frame.elapsedSeconds, frame.result.image.samples.length);
+```
+
+The tests are in `test/exposure-build-up.test.ts`:
+
+- The last fraction equals `simulateCapture` byte for byte: tabulated and lean paths, fixed pattern, dual gain, auto white
+  balance and Auto ISO, camera rotation, rolling shutter, a moving subject and mixed lighting.
+- Each fraction's mean and variance match a single capture at f·t. Under motion this is checked column by column, and the
+  fraction is shown to differ from the whole exposure scaled by f.
+- Without read noise the codes never decrease, and Cov(c₁, c₂) = Var(c₁).
+- Dark frames' read noise is independent between readouts.
+- A fraction past the full well clips.
+
+`test/binomial-sample.test.ts` checks the binomial draws with chi-square tests of the probability mass function.
+
 ### A Print JPEG written in strips
 
 At 1:1 (output size equal to the crop), a Print JPEG's rows can be coded on separate workers.

package/docs/USAGE.md

@@ -7146,6 +7146,7 @@ console.log(png.length, same);
 See [Print planning](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md) for a complete, strict packed example and the exact-ratio integer policy.
 
 - `calculatePrintPlan()` says whether the native sampling is enough, and gives a compatible minimum file raster.
+- `fit: { kind: "contain", paperOrientation }` (2.22.0) fits the whole image inside paper of another shape and reports the borders ([Contain fit](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md#integer-policy-fit-and-sufficiency)).
 - `calculatePrintSizeLimit()` distinguishes finite, unbounded and unavailable sampling limits.
 - `calculatePrintSizeLimitWithBlurAndNoise()` (2.20.0) gives the largest print at a viewing distance that still looks sharp and clean, counting blur and noise as well as pixels, and names the limiting factor ([Print size limit with blur and noise](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md#print-size-limit-with-blur-and-noise)). An approximation.
 - Print quality and delivery are not assessed.
@@ -7512,6 +7513,26 @@ console.log(calculateGeometricFocusBreathing({
 }).value.deltaDegrees);
 ```
 
+## Sensor profiles (#554)
+
+`SENSOR_PROFILES` lists eight representative sensors (full frame, APS-C, medium format and a large phone sensor; BSI,
+stacked and front-illuminated; 2010s and 2020s) whose values come from published specifications, values derived from them
+or labelled design values, with no maker or product named. `simulateCapture({ sensor: { profile: record } })` simulates one
+(the record is checked strictly; `resolveSensorProfile(id)` finds one by id):
+it replaces the body's ISO range, readout regimes, readout time and fixed-pattern noise, and the #555 characteristics
+override it one at a time. `resolveSensorProfile(id)` returns one profile; `SENSOR_PROFILE_ISO_ANCHOR` is the ISO anchor its base ISO is re-rated from. Values, sources and the ISO
+rating: [SENSOR_PROFILES.md](https://github.com/Photivra/photivra/blob/main/docs/SENSOR_PROFILES.md).
+
+```ts
+import { SENSOR_PROFILES, simulateCapture } from "@photivra/engine";
+
+for (const p of SENSOR_PROFILES) {
+  // fast: false (full quality, as the calculator asks) computes the mid-gray noise figure.
+  const r = await simulateCapture({ scene: { preset: "uniform" }, fast: false, sensor: { profile: p }, exposure: { mode: "manual", iso: 3200, shutterSeconds: 1 / 4000 } });
+  console.log(p.name, r.sensor.dynamicRangeStops.toFixed(1), r.sensor.midGrey?.snr.toFixed(1));
+}
+```
+
 ## Generic lens catalogue (#549)
 
 `GENERIC_LENS_CATALOGUE` lists the engine's 30 generic primes (17 professional, 13 consumer, "PV 50 1.2 Pro", "PV 50 1.8"; Photivra's
@@ -7524,7 +7545,9 @@ correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` appl
 `output.lensCorrections` (#570; never to the RAW or the DNG), and which a DNG can carry for RAW editors as optional DNG opcodes with
 `output.dng.lensCorrectionOpcodes` (#587; the RAW codes unchanged). `simulateCapture` renders a catalogue lens with `lens.catalogue`
 ([quick start](QUICK_START.md#generic-lens-catalogue-549)); `fast: true` (or `lens: { catalogue: { kind, fast: true } }`) takes its
-fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures. Equations, tables and the
+fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures.
+`calculateLateralColorFringe({ lensId, activeImagingArea, pixelPitchMicrometers, fieldPosition? })` gives the lens's lateral color as a
+fringe width: the blue-minus-red image displacement in µm and pixels at a field position (default the corner; #580). Equations, tables and the
 chart measurements: [LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
 
 ```ts
@@ -7790,6 +7813,13 @@ including the whole-image stages `output.diffractionCorrection` and `output.shar
 bytes as a whole-frame `simulateCapture()` and per-row progress (`diffraction-correction`, `sharpening`). See
 [Quick start, Developing a capture rendered in parts](QUICK_START.md#developing-a-capture-rendered-in-parts-571).
 
+`simulateExposureBuildUp(options, { fractions })` (#534) renders fractions of one exposure as one accumulating process. Each
+fraction's expected signal is its own capture at the elapsed time, so camera rotation, a moving subject and mixed lighting are
+included. Its photo and dark counts are binomial splits of the next fraction's, so they build up in place. Each fraction is
+clipped at the full well, read out once with its own read noise and developed as its own photo. The fraction at 1 is
+`simulateCapture(options)` byte for byte. Only the sRGB sample formats are accepted (on screen). See
+[Quick start, Exposure build-up](QUICK_START.md#exposure-build-up-534).
+
 ### Color charts (2.14)
 
 The engine's own [color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md) are reflectance spectra lit by the capture's illuminant. Draw the
@@ -7810,6 +7840,33 @@ const sky = getColorPatchSet().patches.find((p) => p.patchId === "sky-blue");
 console.log(tungsten.scene.parameters.patchSet, sky?.code, sky?.name, sky?.reference.cielabD65); // "PV-M1", "Midday Sky"
 ```
 
+### A photo as a print (2.21)
+
+An [image-plane scene](https://github.com/Photivra/photivra/blob/main/docs/IMAGE_PLANE.md) (#581) puts an sRGB (8- or 16-bit) or linear image in front of the camera as a flat matte
+print. Each pixel becomes a smooth reflectance spectrum in [0, 1] that gives back its sRGB under CIE D65. Under other lights the print's colors are an approximation.
+`chartSize` sets the print's size (its height follows the image). Without it the print is fitted inside the frame. `prepareDisplayView` renders it on WebGPU in the Speed path.
+`prepareImagePlaneScenes()` loads the scene's module first, so bundles that never print a photo do not carry it.
+
+```ts
+import { prepareImagePlaneScenes, simulateCapture } from "@photivra/engine";
+
+await prepareImagePlaneScenes(); // loads the scene's module (a lazy chunk) once
+const width = 2, height = 1, data = Uint8Array.of(255, 255, 255, 30, 60, 200);
+const print = await simulateCapture({
+  scene: { kind: "image-plane", sceneId: "snapshot", image: { width, height, channels: 3, encoding: "srgb-8", data }, paper: { whiteReflectance: 0.9 } },
+  chartSize: { widthM: 0.1 },
+  subjectDistanceM: 0.4,
+  output: { width: 32, height: 16 }
+});
+console.log(print.scene.parameters.encoding, print.assumptions.some((a) => a.id === "scene.imagePlane")); // "srgb-8", true
+```
+
+**Representative light sources (2.22).** The engine's own [representative light sources](https://github.com/Photivra/photivra/blob/main/docs/LIGHT_SOURCES.md) are four relative spectra
+designed by Photivra: a tri-phosphor fluorescent tube and white LEDs of low and high color rendering at 4000 K and a warm one at
+2700 K, each "representative, not a named product". `createRepresentativeLightSourceIlluminant({ sourceId })` returns an
+`illuminant` (`{ kind: "spectrum", spectrum, label }`); under the two 4000 K LEDs the color patches differ by up to ΔE00 5.9 while
+the neutrals stay neutral. Use `sensor.spectralStepNanometers: 5`. The page has a runnable example.
+
 In `aperture-priority` mode, the shutter comes from the meter (CIPA DC-004 relations S = 10/H and H = 0.65·L·t/N²) through
 `resolveAperturePriorityExposureMode()`.
 `exposure.standardExposureDeviationStops` is the exposure used minus the standard exposure for the metered luminance L, in stops,
@@ -7866,6 +7923,28 @@ The chart presets are also available on their own:
 - `createPlanarSceneRadianceProvider()` turns a chart into an `evaluateRadiance` callback for the native
   environment RAW contract.
 
+### Mixed lighting (2.22, #550)
+
+`illumination` lights the chart with two or more sources blended across it (a linear gradient, a radial falloff or regions),
+for example window daylight on one side and a lamp on the other. The frame center's light sets the grey-card meter and its
+strongest source the `"scene-illuminant"` white balance; both are reported in `assumptions`. See
+[Mixed lighting](https://github.com/Photivra/photivra/blob/main/docs/MIXED_ILLUMINATION.md) for the model and every field.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const lampPool = await simulateCapture({
+  scene: { preset: "step-wedge" },
+  exposure: { mode: "aperture-priority", metering: "grey-card" },
+  illumination: {
+    sources: [{ illuminant: "cie-a", illuminanceLux: 500 }, { illuminant: { kind: "planckian", temperatureKelvin: 6500 }, illuminanceLux: 20000 }],
+    blend: { kind: "radial", radius: 0.8, stops: [0.25, 1] }
+  },
+  output: { width: 32, height: 16 }
+});
+console.log(lampPool.assumptions.find((a) => a.id === "output.whiteBalanceSource")?.value); // { source: 0, illuminant: "cie-a" }
+```
+
 ### Display view of a capture
 
 `simulateDisplayView(options, view)` takes a capture request and a display size and returns the real
@@ -8051,6 +8130,18 @@ const rolling = await simulateCapture({ scene: { preset: "checkerboard" }, motio
 console.log(rolling.request.siteInput(7 * 8).charge.completenessProfile.startOffsetSecondsFromOpeningReference);
 ```
 
+`motion.subject` (2.22.0) moves the subject instead: the whole scene, or one `region` of it over a still background,
+at `velocityMPerSec` on the scene plane, optionally rotating at `angularVelocityRadPerSec` about the optical axis. It
+uses the same temporal midpoints, so a rolling shutter skews the moving subject. The display view renders sideways
+motion under a global shutter and refuses the rest. See [Subject motion](QUICK_START.md#subject-motion).
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const moving = await simulateCapture({ scene: { preset: "slanted-edge" }, motion: { subject: { velocityMPerSec: { x: 0.5 } } }, output: { width: 8, height: 8 } });
+console.log(moving.assumptions.find((a) => a.id === "motion.subject")?.value);
+```
+
 ## Equivalent f-number, sensor area and blur as a share of the frame
 
 `calculateSensorEquivalence()` says what a lens on one sensor corresponds to on a 36 × 24 mm frame (or on a `reference` you pass). Call it once per sensor to fill a lens table:

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.20.0" as const
+ENGINE_API_VERSION = "2.21.0" as const
 ```

package/docs/api/equipment-generic-lens-catalogue.md

@@ -4,11 +4,11 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 ## GENERIC_LENS_CATALOGUE
 
-The 30 lenses: 17 professional, then 13 consumer, each set by focal length.
+The 33 lenses: 17 professional, 13 consumer and (#554) 3 phone lenses, each set by focal length.
 
 ```ts
 GENERIC_LENS_CATALOGUE: readonly GenericLensCatalogueEntry[] = Object.freeze([...PRO.map((row) => entry("professional", row)),
-  ...CONSUMER.map((row) => entry("consumer", row))])
+  ...CONSUMER.map((row) => entry("consumer", row)), ...PHONE.map((row) => entry("phone", row))])
 ```
 
 ## GENERIC_LENS_IDS
@@ -30,7 +30,12 @@ GENERIC_LENS_SET_BASELINES: Readonly<Record<GenericLensSet, Readonly<GenericLens
     breathingFraction: -0.03, focusScatterDepthOfFocusFraction: 0.1, closeFocusFactor: 0.15 }),
   consumer: Object.freeze({ sphericalWaves: 0.5, comaWaves: 1.0, astigmatismWaves: 0.8, fieldCurvatureWaves: 0.45, axialColorWaves: 0.4,
     lateralColorFraction: 0.0003, distortionMagnitude: 0.03, naturalVignettingStops: 0.7, opticalVignettingStops: 1.1, veilingGlareFraction: 0.02, ghostFraction: 0.008,
-    breathingFraction: -0.08, focusScatterDepthOfFocusFraction: 0.3, closeFocusFactor: 0.5 })
+    breathingFraction: -0.08, focusScatterDepthOfFocusFraction: 0.3, closeFocusFactor: 0.5 }),
+  // #554: design values (docs/LENS_CATALOGUE.md, "Phone lenses"): the consumer baseline with the stronger fall-off, flare and distortion
+  // (corrected in software on phones) of small fixed-aperture phone lenses, and no optical-vignetting change (the aperture is fixed).
+  phone: Object.freeze({ sphericalWaves: 0.5, comaWaves: 1.0, astigmatismWaves: 0.8, fieldCurvatureWaves: 0.5, axialColorWaves: 0.3,
+    lateralColorFraction: 0.0004, distortionMagnitude: 0.03, naturalVignettingStops: 1.2, opticalVignettingStops: 0.5, veilingGlareFraction: 0.03, ghostFraction: 0.01,
+    breathingFraction: -0.05, focusScatterDepthOfFocusFraction: 0.3, closeFocusFactor: 0.5 })
 })
 ```
 
@@ -179,10 +184,10 @@ export type GenericLensKind = "standard" | "macro" | "fisheye";
 
 ## GenericLensSet
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+#554: "phone", the three fixed lenses of a phone sensor profile (`sensor.profile` with `fixedLenses: "phone"`).
 
 ```ts
-export type GenericLensSet = "professional" | "consumer";
+export type GenericLensSet = "professional" | "consumer" | "phone";
 ```
 
 ## ResolvedGenericLens

package/docs/api/equipment-sensor-profile-body.md

@@ -0,0 +1,64 @@
+# equipment/sensor-profile-body.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.
+
+## SENSOR_PROFILE_ISO_ANCHOR
+
+The engine's ISO anchor (see the module comment): white charge 60 000 e⁻ at ISO 100, 36 µm², QE 0.5.
+
+```ts
+SENSOR_PROFILE_ISO_ANCHOR = Object.freeze({ iso: 100, fullWellElectrons: 60000, pixelAreaSquareMicrometers: 36, peakQuantumEfficiency: .5 })
+```
+
+## SensorProfile
+
+One sensor profile. Every number is per photosite unless stated; see `provenance` for each value's kind.
+
+```ts
+export interface SensorProfile {
+  id: string;
+  /** Format, resolution, architecture and era; no maker or product name. */
+  name: string;
+  /** A market category, not a specification: it is a label and changes nothing. */
+  marketTag: "consumer" | "professional";
+  architecture: "front-illuminated" | "back-illuminated" | "stacked";
+  sensorWidthMm: number; sensorHeightMm: number;
+  pixelsWide: number; pixelsHigh: number;
+  pixelPitchMicrometers: number;
+  /** The green channel's peak EQE (#555 `peakQuantumEfficiency`). */
+  peakQuantumEfficiency: number;
+  /** Full-well capacity, e⁻: the charge at the RAW white level at base ISO. */
+  fullWellElectrons: number;
+  /** Read noise, RMS e⁻; `highGainFromIso` null for one conversion gain throughout. */
+  readNoise: { lowGainElectrons: number; highGainElectrons: number; highGainFromIso: number | null };
+  /** Charge storage limit of the high conversion gain, e⁻ (null without one): full well × base ISO / switch ISO. */
+  highGainFullWellElectrons: number | null;
+  adcBitDepth: 12 | 14 | 16;
+  /** Re-rated base ISO (see the module comment) and the highest ISO setting. */
+  baseIso: number; maximumIso: number;
+  /** Largest analog gain relative to base ISO; above it the gain is digital. */
+  maximumAnalogGain: number;
+  /** Rolling readout, s: the top-to-bottom skew with `motion.shutter: "rolling"`. */
+  readoutSeconds: number;
+  /** Fixed-pattern noise used with `sensor.fixedPatternNoise` (EMVA 1288 Release 4.0 non-uniformities). */
+  fixedPattern: { prnu: number; dsnu: number; hotPixelFraction: number; hotPixelMultiplier: number; rowElectrons: number; columnElectrons: number };
+  /** What the profile is good for (text only). */
+  goodFor: readonly string[];
+  description: string;
+  /** "phone": the profile takes only the catalogue's phone lenses (`lens.catalogue`), which need it. */
+  fixedLenses: "phone" | null;
+  /**
+   * Each value's kind and source key (S1–S10, docs/SENSOR_PROFILES.md "Sources"); a value not listed is a design value.
+   * For example `fullWellElectrons: "published S1"` or `baseIso: "derived"`.
+   */
+  provenance: Readonly<Partial<Record<keyof SensorProfile | "sensorSize" | "pixels" | "highGainFromIso", string>>>;
+}
+```
+
+## SensorProfileValueKind
+
+How a profile value was obtained: copied from a source, calculated from sourced values, or Photivra's design value.
+
+```ts
+export type SensorProfileValueKind = "published" | "derived" | "design";
+```