@photivra/engine 2.20.0 → 2.22.0

package/docs/api/capture-dng-opcodes.md

@@ -0,0 +1,93 @@
+# capture/dng-opcodes.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.
+
+## applyDngOpcodes
+
+Applies an opcode list to a stage image in place (WarpRectilinear returns a new buffer in `image.data`). Returns one assumption
+per opcode: what was applied, or why it was not.
+
+```ts
+export function applyDngOpcodes(image: DngStageImage, opcodes: readonly DngOpcode[], options: ApplyDngOpcodesOptions): string[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngOpcodesOptions
+
+Options of {@link applyDngOpcodes}.
+
+```ts
+export interface ApplyDngOpcodesOptions {
+  /** 1, 2 or 3: the list's stage (for the report). */
+  stage: 1 | 2 | 3;
+  /**
+   * WarpRectilinear resampling: false (full quality) uses cubic convolution (Keys, a = −0.75, the DNG SDK's kernel); true uses
+   * bilinear interpolation (fast). Registered as "dngImport.warpRectilinear" in SIMULATE_CAPTURE_FAST_METHODS.
+   */
+  fast: boolean;
+  /** 1, or 0.5 for a half-size image: pixel-coordinate parameters are scaled; pitched areas and bad pixels are then not applied. */
+  scale?: 1 | 0.5;
+}
+```
+
+## DngOpcode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngOpcode {
+  id: number;
+  /** The specification's name, or "Unknown". */
+  name: string;
+  dngVersion: [number, number, number, number];
+  /** Flag bit 0: a reader may skip it. */
+  optional: boolean;
+  /** Flag bit 1: may be skipped for preview-quality rendering. */
+  previewSkip: boolean;
+  /** Decoded parameters of an applied opcode; null for one this reader does not apply. */
+  parameters: DngOpcodeParameters | null;
+}
+```
+
+## DngOpcodeArea
+
+The rectangle, plane range and pitch an area-based opcode acts on (stage pixel coordinates, bottom and right exclusive).
+
+```ts
+export interface DngOpcodeArea { top: number; left: number; bottom: number; right: number; plane: number; planes: number; rowPitch: number; colPitch: number }
+```
+
+## DngOpcodeParameters
+
+Opcode parameters, by opcode.
+
+```ts
+export type DngOpcodeParameters =
+  | { opcode: "WarpRectilinear"; planes: { radial: [number, number, number, number]; tangential: [number, number] }[]; centerX: number; centerY: number }
+  | { opcode: "FixVignetteRadial"; coefficients: [number, number, number, number, number]; centerX: number; centerY: number }
+  | { opcode: "FixBadPixelsConstant"; constant: number; bayerPhase: number }
+  | { opcode: "FixBadPixelsList"; bayerPhase: number; points: [number, number][]; rects: [number, number, number, number][] }
+  | { opcode: "MapTable"; area: DngOpcodeArea; table: Uint16Array }
+  | { opcode: "MapPolynomial"; area: DngOpcodeArea; coefficients: number[] }
+  | { opcode: "GainMap"; area: DngOpcodeArea; pointsV: number; pointsH: number; spacingV: number; spacingH: number; originV: number; originH: number; mapPlanes: number; gains: Float32Array }
+  | { opcode: "DeltaPerRow" | "DeltaPerColumn" | "ScalePerRow" | "ScalePerColumn"; area: DngOpcodeArea; values: Float32Array };
+```
+
+## DngStageImage
+
+A stage image: interleaved (row, column, plane), normalized values.
+
+```ts
+export interface DngStageImage { width: number; height: number; planes: number; data: Float32Array }
+```
+
+## parseDngOpcodeList
+
+Parses an opcode list (the tag's bytes). Every count and length is checked against the bytes before allocation.
+
+```ts
+export function parseDngOpcodeList(bytes: Uint8Array): DngOpcode[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-dng-profile-maps.md

@@ -0,0 +1,141 @@
+# capture/dng-profile-maps.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.
+
+## applyDngProfileGainTableMap
+
+Applies ProfileGainTableMap(2): at each pixel the weight t = clamp(w·(R, G, B, min, max)·2^BaselineExposure, 0, 1)^γ selects a
+gain by linear interpolation at t·N in the table (index clamped to N − 1, SDK), bilinear between map points at the pixel centre's
+relative position (held at the map's edges); R, G and B are multiplied by it.
+
+```ts
+export function applyDngProfileGainTableMap(input: ApplyDngProfileGainTableMapInput): void;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngProfileGainTableMapInput
+
+Options of {@link applyDngProfileGainTableMap}.
+
+```ts
+export interface ApplyDngProfileGainTableMapInput {
+  /** Linear ProPhoto (RIMM, D50) RGB, white-balanced, 1 = clipping white; changed in place. */
+  image: DngRgbImage;
+  map: DngProfileGainTableMap;
+  /** BaselineExposure (stops) not yet applied to `image`: the weight is scaled by 2^stops, as the SDK does. Default 0. */
+  baselineExposureStops?: number;
+  /** Where `image` sits in the stage-3 (ActiveArea) image the map spans. Default: `image` is the whole stage-3 image. */
+  region?: { x: number; y: number; stageWidth: number; stageHeight: number };
+  /** Keep values above 1 (true) or clip to 0..1 (false, the SDR default). */
+  overrange?: boolean;
+}
+```
+
+## applyDngRgbTables
+
+Applies RGBTables: each table maps ProPhoto RGB into its own primaries (clipped to 0..1, the clipped-off part kept and added back
+when GamutExtension is "extend"), encodes it with the table's gamma, interpolates tetrahedrally in the 3D table, decodes and maps
+back (SDK `RefRGBtoRGBTable3D`). The background table (empty name) applies to the whole image. Weighted sum: each masked table's
+result weighted by its mask, the background (the background table's result, or the input) by 1 − min(1, Σ masks), normalized.
+Sequential: each table in file order, blended into the running image by its mask (the background table by 1 − min(1, Σ other masks)).
+A table whose mask is not supplied is skipped (as the SDK skips a name with no SemanticMask); the returned notes say so.
+
+```ts
+export function applyDngRgbTables(input: ApplyDngRgbTablesInput): string[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngRgbTablesInput
+
+Options of {@link applyDngRgbTables}.
+
+```ts
+export interface ApplyDngRgbTablesInput {
+  /** ProPhoto-primaries RGB after the tone curve, 0..1; changed in place. */
+  image: DngRgbImage;
+  tables: DngRgbTables;
+  /** Semantic masks by name (values 0..1, any size; stretched over the image with bilinear interpolation). */
+  masks?: readonly { name: string; width: number; height: number; data: Float32Array }[];
+}
+```
+
+## DngProfileGainTableMap
+
+A parsed ProfileGainTableMap(2): N gains at each of V × H map points, decoded to 32-bit floats.
+
+```ts
+export interface DngProfileGainTableMap {
+  /** 1 for ProfileGainTableMap (52525), 2 for ProfileGainTableMap2 (52544). */
+  version: 1 | 2;
+  pointsV: number; pointsH: number; spacingV: number; spacingH: number; originV: number; originH: number;
+  /** MapPointsN: the table length at each map point. */
+  tablePoints: number;
+  /** MapInputWeights for red, green, blue, min(R,G,B) and max(R,G,B). */
+  inputWeights: [number, number, number, number, number];
+  /** PGTM2: the weight's gamma (1 for version 1). */
+  gamma: number;
+  /** Gains, row-major (v, h, table point). */
+  gains: Float32Array;
+}
+```
+
+## DngRgbImage
+
+An RGB image, interleaved (row, column, channel).
+
+```ts
+export interface DngRgbImage { width: number; height: number; data: Float32Array }
+```
+
+## DngRgbTable
+
+One table of RGBTables: a 3D table of `divisions`³ RGB samples (16-bit, 65535 = 1).
+
+```ts
+export interface DngRgbTable {
+  /** TableSemanticName: the semantic mask it applies within; "" for the background table (the whole image). */
+  semanticName: string;
+  divisions: number;
+  gamma: "linear" | "srgb" | "1.8" | "2.2" | "rec2020";
+  primaries: "srgb" | "adobe-rgb" | "display-p3" | "rec2020" | "prophoto";
+  gamut: "clip" | "extend";
+  /** RGB per node, red slowest then green then blue, length divisions³ × 3. */
+  samples: Uint16Array;
+}
+```
+
+## DngRgbTables
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngRgbTables { compositeMethod: "weighted-sum" | "sequential"; tables: DngRgbTable[] }
+```
+
+## parseDngProfileGainTableMap
+
+Parses ProfileGainTableMap (version 1) or ProfileGainTableMap2 (version 2). Layout: MapPointsV, MapPointsH (LONG), MapSpacingV,
+MapSpacingH, MapOriginV, MapOriginH (DOUBLE), MapPointsN (LONG), MapInputWeights (5 FLOAT); version 2 adds DataType (LONG: 0 uint8,
+1 uint16, 2 float16, 3 float32), Gamma, GainMin, GainMax (FLOAT); then the gains. Integer gains are GainMin + (x/max)·(GainMax −
+GainMin). A single map point on an axis has spacing 1 and origin 0 (SDK).
+
+```ts
+export function parseDngProfileGainTableMap(bytes: Uint8Array, littleEndian: boolean, version: 1 | 2): DngProfileGainTableMap;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseDngRgbTables
+
+Parses RGBTables (52543): table count (LONG, at most 20; 0 means none), CompositeMethod (LONG: 0 weighted sum, 1 sequential), then
+per table LengthTableSemanticName (SHORT), the name's bytes, Divisions, PixelType (0 uint8, 1 uint16, 2 float32), GammaEncoding
+(0 linear, 1 sRGB, 2 γ 1.8, 3 γ 2.2, 4 Rec. 2020), ColorPrimaries (0 sRGB, 1 Adobe RGB, 2 P3, 3 Rec. 2020, 4 ProPhoto) and
+GamutExtension (0 clip, 1 extend), each a BYTE, then Divisions³ RGB samples (uint8 scaled by 256, float scaled by 65535).
+
+```ts
+export function parseDngRgbTables(bytes: Uint8Array, littleEndian: boolean): DngRgbTables | null;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-dng-stage-image.md

@@ -0,0 +1,43 @@
+# capture/dng-stage-image.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.
+
+## developDngStageImage
+
+Builds the stage-2 (CFA) or stage-3 (LinearRaw) image of an imported DNG, normalized 0..1, interleaved by sample.
+
+```ts
+export function developDngStageImage(raw: ImportedDngRaw, options: DevelopDngStageImageOptions = {}): DngStageImageResult;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DevelopDngStageImageOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DevelopDngStageImageOptions {
+  /** The output the development is for ("srgb-8" or "srgb-16" on screen; "dng", "jpeg" or "png" exports). Default "srgb-8" (fast; owner, 2026-11-11). */
+  format?: "srgb-8" | "srgb-16" | "dng" | "jpeg" | "png";
+  /** The speed-versus-accuracy choice (WarpRectilinear resampling); default from `format` (fast on screen, full for exports). */
+  fast?: boolean;
+  /** Apply the opcode lists (default true). */
+  opcodes?: boolean;
+}
+```
+
+## DngStageImageResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngStageImageResult extends DngStageImage {
+  /** 3 for LinearRaw (every opcode list applied), 2 for a CFA mosaic (OpcodeList3 left to the caller). */
+  stage: 2 | 3;
+  /** The resolved `fast` and where it came from. */
+  fast: { requested: boolean; defaultedFrom: "request" | "format" };
+  /** What was applied and what was not. */
+  assumptions: string[];
+}
+```

package/docs/api/capture-jpeg-xl-tiles.md

@@ -0,0 +1,33 @@
+# capture/jpeg-xl-tiles.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.
+
+## createJxlOxideDngDecoder
+
+A {@link DngJpegXlDecoder} over jxl-oxide-wasm: `forceSrgb` off (the samples stay in the codestream's encoding), one render per
+tile, and the image object freed after it. Usage: `import init, * as jxl from "jxl-oxide-wasm"; await init();
+createJxlOxideDngDecoder(jxl)`.
+
+```ts
+export function createJxlOxideDngDecoder(module: JxlOxideModule): DngJpegXlDecoder;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DngJpegXlDecoder
+
+Decodes one JPEG XL codestream (a DNG strip or tile) to PNG bytes in the codestream's own colour encoding (no colour conversion).
+
+```ts
+export type DngJpegXlDecoder = (codestream: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+```
+
+## JxlOxideModule
+
+The part of the jxl-oxide-wasm module the adapter uses (its `JxlImage` class, after the module's `init`).
+
+```ts
+export interface JxlOxideModule {
+  JxlImage: new () => { feedBytes(bytes: Uint8Array): unknown; tryInit(): boolean; render(): { encodeToPng(): Uint8Array }; forceSrgb: boolean; free(): void };
+}
+```

package/docs/api/capture-lossy-jpeg.md

@@ -0,0 +1,41 @@
+# capture/lossy-jpeg.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.
+
+## LossyJpegImage
+
+Decoded samples, interleaved by component within each line (line, x, component), 0..255.
+
+```ts
+export interface LossyJpegImage {
+  width: number;
+  height: number;
+  components: number;
+  /** "ycbcr-to-rgb" when three YCbCr components were converted to RGB; "none" otherwise. */
+  colorTransform: "ycbcr-to-rgb" | "none";
+  samples: Uint8Array;
+}
+```
+
+## LossyJpegLimits
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LossyJpegLimits {
+  /** Largest width x height x components accepted, checked before any sample buffer is allocated. */
+  maximumSamples: number;
+  /** An abbreviated table-specification stream (SOI, DQT/DHT, EOI) read before `bytes`, as DNG's JPEGTables tag (347) supplies. */
+  tables?: Uint8Array;
+}
+```
+
+## parseLossyJpeg
+
+Decodes one DCT JPEG stream (see the module notes). Every length, count and table index is checked against the buffer.
+
+```ts
+export function parseLossyJpeg(bytes: Uint8Array, limits: LossyJpegLimits): LossyJpegImage;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -136,7 +136,8 @@ RAW saturation handled before white balance. Counts are pixels or samples of the
 
 ```ts
 export interface RawHighlightDiagnostics {
-  mode: RawHighlightMode;
+  /** #602: "reconstruct-neighbors" from `simulateCapture`'s whole-image neighbor reconstruction. */
+  mode: RawHighlightMode | "reconstruct-neighbors";
   /** Output pixels with at least one contributing site at or above its white level, or flagged as saturated. */
   saturatedPixelCount: number;
   /** `clip`: WB-scaled samples clipped at the smallest gain. Always 0 for `reconstruct`. */

package/docs/api/core-execution-error.md

@@ -0,0 +1,43 @@
+# core/execution-error.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.
+
+## ImageKernelExecutionError
+
+Domain error for getting and running a backend. Input validation still throws the engine's existing errors.
+
+```ts
+export class ImageKernelExecutionError extends Error {
+  readonly code = "IMAGE_KERNEL_EXECUTION";
+  readonly reason: ImageKernelFailureReason;
+
+  constructor(reason: ImageKernelFailureReason, message: string) {
+    super(message);
+    this.name = "ImageKernelExecutionError";
+    this.reason = reason;
+  }
+}
+```
+
+## ImageKernelFailureReason
+
+Failure classes reported by {@link ImageKernelExecutionError}. `conformance-failed` (#481): a device failed the display view's
+run-time self-check with `gpu: "require"`. `quality-code-unavailable` (2.22.0, #594): on-demand full-quality code could not be
+loaded (for example a failed chunk download); `prepareQualityPaths()` rejects with it, a display-view render with `gpu: "require"`
+fails with it (with `gpu: "auto"` it runs the CPU reference), and a CPU request whose full-quality or opt-in code does not load
+fails with it (nothing is remembered: the next request tries again).
+
+```ts
+export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification" | "conformance-failed" |
+  "quality-code-unavailable";
+```
+
+## ImageKernelFallbackReason
+
+Why a requested `webgpu-f32` backend ran the CPU reference instead. `webgpu-disabled`: `setWebGpuEnabled(false)` in this realm.
+
+```ts
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "webgpu-disabled" | "adapter-unavailable" | "device-request-failed" |
+  "insufficient-limits" | "unsupported-platform-endianness";
+```

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.22.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";
+```

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)))
+```