@photivra/engine 2.19.0 → 2.21.0

package/docs/USAGE.md

@@ -7146,7 +7146,9 @@ 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.
 
 The [regional Print detail diagnostic](https://github.com/Photivra/photivra/blob/main/docs/PRINT_DETAIL_ASSESSMENT.md) measures one declared, coherent sinusoidal fundamental in a selected linear-luminance ROI, and records the exact pipeline stage it measured. Its [validation protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_DETAIL_VALIDATION.md) and [capability ledger](https://github.com/Photivra/photivra/blob/main/docs/validation/print-detail-capabilities.json) separate mathematical conformance from the still-blocked qualification of acquired images, renderers and perceived quality.
@@ -7511,17 +7513,41 @@ 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
 own designs, not real products). `resolveGenericLens` resolves one for a sensor, an f-number and a focus distance: its focal length
 (scaled by the crop factor), aperture range, close focus, projection and its character, Seidel aberrations, axial and lateral
-colour, distortion and vignetting profiles, flare, breathing and focus scatter, each a labelled approximation.
+colour, distortion and vignetting profiles, flare, breathing, focus scatter and its bokeh (`character.bokeh`, #567: the options of
+`lens.defocus` and `calculateDefocusBokehKernel`), each a labelled approximation.
 `simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
 correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` applies to its developed image with
-`output.lensCorrections` (#570; never to the RAW or the DNG). `simulateCapture` renders a catalogue lens with `lens.catalogue`
+`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
@@ -7787,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
@@ -7807,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,
@@ -7863,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
@@ -8048,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:
@@ -8085,3 +8179,63 @@ console.log(share.print?.blurOnPrintMm); // 0.25 mm on the print
 - Equal shares of the frame diagonal look the same when images are shown at the same size. `calculateBlurShareOfFrame()` does not judge whether a blur is visible.
 
 See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#sensor-equivalence-f-number-area-and-blur-share).
+
+## Aperture diameter and cropping to match a longer lens
+
+`calculateApertureDiameter()` gives the entrance-pupil diameter in millimetres, focal length ÷ f-number (exact by the definition of the f-number, ideal lens focused at infinity). `calculateCropToMatchFocalLength()` gives the centred crop that makes an image from a shorter lens match a longer lens's framing from the same position, and the pixels it leaves:
+
+```ts
+import { calculateApertureDiameter, calculateCropToMatchFocalLength } from "@photivra/engine";
+
+console.log(calculateApertureDiameter({ focalLengthMm: 50, fNumber: 2 }).value.entrancePupilDiameterMm); // 25
+console.log(calculateApertureDiameter({ focalLengthMm: 50, fNumber: 4 }).value.entrancePupilDiameterMm); // 12.5
+
+const crop = calculateCropToMatchFocalLength({
+  focalLengthMm: 50,
+  targetFocalLengthMm: 100,
+  pixelWidth: 6000,
+  pixelHeight: 4000
+}).value;
+
+console.log(crop.cropFactor); // 2
+console.log(crop.pixelWidth, crop.pixelHeight); // 3000 2000
+console.log(crop.megapixels, crop.sourceMegapixels); // 6 24
+```
+
+- The aperture diameter is the entrance pupil (the aperture stop seen from the front of the lens), not the diaphragm's opening. Close focus (working f-number `N·(1 + m/P)`, pupil magnification `P`) is not modelled.
+- The crop factor `target ÷ focal length` is exact for ideal rectilinear lenses focused at infinity; at close focus the matching factor is larger, `F·(d − f)/(f·(d − F))` at object distance `d` (thin lens), which is not applied. The crop is `calculateCenteredCrop()`'s (aspect ratio kept to whole pixels), and `targetFocalLengthMm` must be at least `focalLengthMm`.
+
+See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#aperture-entrance-pupil-diameter).
+
+## Which limits detail: the lens or the sensor
+
+`calculateDetailLimit()` (model `detail-limit` 1.0.0, #575) answers "would a sharper lens or a denser sensor help?" for given settings. It returns the optics' resolution (MTF50 in cycles/mm, from diffraction, the lens's aberrations and any defocus), the sampling's (the Nyquist frequency 1/(2p) and, with a Bayer filter, the red and blue sites' 1/(4p)), the system MTF50, and which one limits:
+
+```ts
+import { calculateDetailLimit } from "@photivra/engine";
+
+const sensor = { widthMm: 36, heightMm: 24, pixelWidth: 6000 }; // 6 µm pixels
+
+const stoppedDown = calculateDetailLimit({ sensor, lens: { kind: "ideal", focalLengthMm: 50 }, fNumber: 22 }).value;
+console.log(stoppedDown.limitedBy, stoppedDown.limitingFactor); // "lens" "diffraction"
+console.log(stoppedDown.optics.mtf50CyclesPerMm); // ≈ 33.4, against a Nyquist frequency of ≈ 83.3
+console.log(stoppedDown.diffractionLimitedFNumber); // ≈ 8.8: from here on diffraction limits on this sensor
+
+const wideOpen = calculateDetailLimit({ sensor, lens: { kind: "catalogue", lensId: "pv-50-1.2-pro" }, fNumber: 4 }).value;
+console.log(wideOpen.limitedBy, wideOpen.limitingFactor); // "sensor" "pixel-pitch"
+
+const outOfFocus = calculateDetailLimit({
+  sensor,
+  lens: { kind: "ideal", focalLengthMm: 50 },
+  fNumber: 2,
+  focus: { focusDistanceM: 3, subjectDistanceM: 2.5 }
+}).value;
+console.log(outOfFocus.limitingFactor); // "defocus"
+```
+
+- The sensor limits when the optics still pass 50 % contrast at the Nyquist frequency (`opticsToNyquistRatio ≥ 1`): a denser sensor would record finer detail. Otherwise the lens limits, through `"diffraction"` when its RMS wavefront error is within λ/14 (the Maréchal criterion), else `"aberrations"` or `"defocus"`, whichever is larger. This rule is an approximation; the MTF values are the exact scalar OTF of the stated wavefront at one wavelength (550 nm unless `wavelengthNm` is given).
+- `lens.catalogue` lenses use their generic Seidel aberrations at `fieldPosition` (0 the center, 1 the corner), so corners are softer; `lens.ideal` has none.
+- Tangential and sagittal MTF50 are both reported; the decision uses the lower one.
+- Demosaicing, sharpening, noise and motion are not included.
+
+See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#which-limits-detail-the-lens-or-the-sensor).

package/docs/api/capture-native-raw-dng.md

@@ -82,5 +82,11 @@ export interface SerializeNativeRawDngInput {
   capturedAtUtc?: string;
   /** Optional (2.4) caller text: description, software, copyright, comment (see the module notes). If omitted, no text is added. */
   textMetadata?: OutputTextMetadata;
+  /**
+   * Optional (#587) OpcodeList3 (tag 51022) bytes, for example `createDngLensCorrectionOpcodes(...).opcodeList3`: a big-endian DNG
+   * opcode list (DNG 1.3.0.0+, "Opcode List Processing") that readers apply to the demosaiced stage-3 image. Only its framing is
+   * checked (count, per-opcode headers and parameter sizes filling the bytes exactly). The RAW codes are unchanged. If omitted, no tag.
+   */
+  opcodeList3?: Uint8Array;
 }
 ```

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.19.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 })
 })
 ```
 
@@ -69,7 +74,7 @@ export interface GenericLensCatalogueEntry {
   note: string;
   /**
    * A short plain-English summary of the lens's character (at most 40 characters, US spelling), written from its adjustments and
-   * `note`, for lists and pickers. It describes only what the catalogue models (bokeh shape is not modeled: the defocus is a disc).
+   * `note`, for lists and pickers. It describes the lens's sharpness, color, distortion and falloff, not its bokeh (the same rule for every lens of a set).
    */
   summary: string;
 }
@@ -102,6 +107,11 @@ export interface GenericLensCharacter {
   breathing: { fieldOfViewChange: number; atMinimumFocus: number };
   /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
   focusScatterDepthOfFocusFraction: number;
+  /**
+   * Bokeh character (#567) at this f-number, focus and sensor, as the options of `lens.defocus` and `calculateDefocusBokehKernel`
+   * (#553): blades, the resolved W040 as `sphericalAberration` (µm at this f-number) and, for fast wides and normals, `catsEye`.
+   */
+  bokeh: DefocusBokehOptions;
 }
 ```
 
@@ -127,7 +137,7 @@ export interface GenericLensCharacterValues {
   distortionMagnitude: number;
   /** Corner fall-off in stops that stays when stopped down (natural vignetting). */
   naturalVignettingStops: number;
-  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone two stops down. */
+  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone four stops down (N = 4·N0). */
   opticalVignettingStops: number;
   /** Veiling glare: the fraction of the image's mean irradiance spread as a uniform veil. */
   veilingGlareFraction: number;
@@ -174,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";
+```

package/docs/api/equipment-sensor-profiles.md

@@ -0,0 +1,86 @@
+# equipment/sensor-profiles.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.
+
+## resolveSensorProfile
+
+The profile record with this id (for `sensor.profile`); a clear error listing the ids otherwise.
+
+```ts
+export function resolveSensorProfile(id: unknown): SensorProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_PROFILE_IDS
+
+The profile ids, in catalogue order.
+
+```ts
+SENSOR_PROFILE_IDS: readonly string[] = Object.freeze(SENSOR_PROFILES.map((p) => p.id))
+```
+
+## SENSOR_PROFILES
+
+The catalogue, in the issue's order. Frozen.
+
+```ts
+SENSOR_PROFILES: readonly SensorProfile[] = Object.freeze(([
+  { id: "full-frame-24mp-bsi-2020s", name: "Full frame 24 MP BSI, 2020s", marketTag: "consumer", architecture: "back-illuminated",
+    sensorWidthMm: 36.07, sensorHeightMm: 24.01, pixelsWide: 6072, pixelsHigh: 4042, pixelPitchMicrometers: 5.94, peakQuantumEfficiency: .8,
+    fullWellElectrons: 100000, readNoise: { lowGainElectrons: 6.4, highGainElectrons: 1.1, highGainFromIso: 500 }, highGainFullWellElectrons: 20000,
+    adcBitDepth: 14, baseIso: 100, maximumIso: 51200, maximumAnalogGain: 64, readoutSeconds: .05, fixedPattern: BSI,
+    goodFor: ["landscape", "portrait", "travel"], description: "Large pixels and a deep full well for wide dynamic range at base ISO; a moderate readout shows some rolling-shutter skew.",
+    fixedLenses: null, provenance: { ...sourced("S1", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "readNoise", "adcBitDepth"),
+      sensorSize: "derived", architecture: "published S1", highGainFromIso: "derived S1", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-45mp-stacked-2020s", name: "Full frame 45 MP stacked, 2020s", marketTag: "professional", architecture: "stacked",
+    sensorWidthMm: 36, sensorHeightMm: 24, pixelsWide: 8256, pixelsHigh: 5504, pixelPitchMicrometers: 4.36, peakQuantumEfficiency: .8,
+    fullWellElectrons: 69000, readNoise: { lowGainElectrons: 3.5, highGainElectrons: 1.5, highGainFromIso: 250 }, highGainFullWellElectrons: 22080,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .005, fixedPattern: BSI,
+    goodFor: ["landscape", "studio", "wildlife"], description: "High resolution with a fast stacked readout: fine detail for landscape and studio work, little rolling-shutter skew for action.",
+    fixedLenses: null, provenance: { pixelPitchMicrometers: "derived", fullWellElectrons: "design (S2 scaled by pixel area)", readNoise: "design (S2)", highGainFromIso: "design (S2)",
+      highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-24mp-stacked-sports-2020s", name: "Full frame 24 MP stacked (sports), 2020s", marketTag: "professional", architecture: "stacked",
+    sensorWidthMm: 36, sensorHeightMm: 24, pixelsWide: 6000, pixelsHigh: 4000, pixelPitchMicrometers: 6, peakQuantumEfficiency: .8,
+    fullWellElectrons: 80000, readNoise: { lowGainElectrons: 3, highGainElectrons: 1, highGainFromIso: 400 }, highGainFullWellElectrons: 25000,
+    adcBitDepth: 14, baseIso: 125, maximumIso: 102400, maximumAnalogGain: 64, readoutSeconds: .0025, fixedPattern: BSI,
+    goodFor: ["sports", "wildlife", "journalism"], description: "The fastest readout and low high-gain read noise: almost no rolling-shutter skew and clean high ISO, at a moderate resolution.",
+    fixedLenses: null, provenance: { pixelPitchMicrometers: "derived", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-24mp-fsi-2010s", name: "Full frame 24 MP front-illuminated, 2010s", marketTag: "professional", architecture: "front-illuminated",
+    sensorWidthMm: 36.01, sensorHeightMm: 24.07, pixelsWide: 6032, pixelsHigh: 4032, pixelPitchMicrometers: 5.97, peakQuantumEfficiency: .53,
+    fullWellElectrons: 76000, readNoise: { lowGainElectrons: 4, highGainElectrons: 4, highGainFromIso: null }, highGainFullWellElectrons: null,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .08, fixedPattern: FSI,
+    goodFor: ["portrait", "landscape", "journalism"], description: "An older professional sensor: lower QE and one conversion gain, so a modern consumer BSI sensor beats it at high ISO; slow readout.",
+    fixedLenses: null, provenance: { ...sourced("S3", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "adcBitDepth"),
+      sensorSize: "derived", architecture: "derived S4", baseIso: "derived" } },
+  { id: "aps-c-24mp-fsi-2020s", name: "APS-C 24 MP front-illuminated, 2020s", marketTag: "consumer", architecture: "front-illuminated",
+    sensorWidthMm: 23.55, sensorHeightMm: 15.73, pixelsWide: 6024, pixelsHigh: 4024, pixelPitchMicrometers: 3.91, peakQuantumEfficiency: .55,
+    fullWellElectrons: 36000, readNoise: { lowGainElectrons: 2.7, highGainElectrons: 2.7, highGainFromIso: null }, highGainFullWellElectrons: null,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .06, fixedPattern: FSI,
+    goodFor: ["travel", "family", "learning"], description: "A smaller, front-illuminated sensor: less light per pixel, a slower readout and more rolling-shutter skew.",
+    fixedLenses: null, provenance: { ...sourced("S5", "pixels", "pixelPitchMicrometers", "architecture", "fullWellElectrons", "readNoise", "adcBitDepth"), sensorSize: "derived", baseIso: "derived" } },
+  { id: "aps-c-26mp-bsi-2020s", name: "APS-C 26 MP BSI, 2020s", marketTag: "professional", architecture: "back-illuminated",
+    sensorWidthMm: 23.49, sensorHeightMm: 15.7, pixelsWide: 6248, pixelsHigh: 4176, pixelPitchMicrometers: 3.76, peakQuantumEfficiency: .8,
+    fullWellElectrons: 50000, readNoise: { lowGainElectrons: 3.3, highGainElectrons: 1, highGainFromIso: 250 }, highGainFullWellElectrons: 16000,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .025, fixedPattern: BSI,
+    goodFor: ["wildlife", "sports", "travel"], description: "A BSI APS-C sensor with dual conversion gain whose readout beats the consumer full-frame profile's.",
+    fixedLenses: null, provenance: { ...sourced("S6", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "readNoise"), sensorSize: "derived",
+      architecture: "published S6", highGainFromIso: "design (S7)", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "medium-format-100mp-bsi-16bit", name: "Medium format 100 MP BSI, 16-bit", marketTag: "professional", architecture: "back-illuminated",
+    sensorWidthMm: 43.856, sensorHeightMm: 32.9, pixelsWide: 11656, pixelsHigh: 8750, pixelPitchMicrometers: 3.76, peakQuantumEfficiency: .8,
+    fullWellElectrons: 50300, readNoise: { lowGainElectrons: 3.3, highGainElectrons: 1, highGainFromIso: 250 }, highGainFullWellElectrons: 16096,
+    adcBitDepth: 16, baseIso: 80, maximumIso: 12800, maximumAnalogGain: 64, readoutSeconds: .25, fixedPattern: BSI,
+    goodFor: ["studio", "landscape", "portrait"], description: "A large sensor with 100 MP and a 16-bit RAW; a slow readout makes its electronic shutter unsuited to motion.",
+    fixedLenses: null, provenance: { ...sourced("S7", "pixels", "pixelPitchMicrometers", "sensorSize", "fullWellElectrons", "readNoise", "adcBitDepth"), architecture: "published S8",
+      highGainFromIso: "derived S7", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "phone-50mp-stacked", name: "Phone, large, 50 MP stacked", marketTag: "consumer", architecture: "stacked",
+    sensorWidthMm: 9.844, sensorHeightMm: 7.431, pixelsWide: 8192, pixelsHigh: 6144, pixelPitchMicrometers: 1.197, peakQuantumEfficiency: .75,
+    fullWellElectrons: 8600, readNoise: { lowGainElectrons: 3, highGainElectrons: 1.4, highGainFromIso: 160 }, highGainFullWellElectrons: 2150,
+    adcBitDepth: 12, baseIso: 40, maximumIso: 6400, maximumAnalogGain: 64, readoutSeconds: 1 / 30,
+    fixedPattern: { prnu: .008, dsnu: .3, hotPixelFraction: 2e-4, hotPixelMultiplier: 50, rowElectrons: .2, columnElectrons: .2 },
+    goodFor: ["everyday", "travel", "family"], description: "A large phone sensor: tiny pixels with a small full well, so less dynamic range and more noise per pixel; simulated as a single frame (no multi-frame stacking).",
+    fixedLenses: "phone", provenance: { ...sourced("S9", "pixels", "pixelPitchMicrometers", "sensorSize", "architecture", "adcBitDepth"), fullWellElectrons: "design (S10 scaled by pixel area)",
+      readNoise: "high gain published S10, low gain design", highGainFullWellElectrons: "derived", readoutSeconds: "derived S9 (1 / full-resolution frame rate)",
+      fixedPattern: "PRNU, row and column published S10; the rest design", baseIso: "derived" } }
+] satisfies SensorProfile[]).map((p) => Object.freeze(p)))
+```