@photivra/engine 1.5.0 → 2.1.0

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

@@ -1,18 +1,32 @@
 # capture/native-raw-development.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## createNativeRawDevelopmentTask
 
-Validates complete phase/halo support, snapshots RAW once, and yields between 256-pixel output tiles.
-Retains explicit acquisition tile width when reconstructing the exact packed plan. Omitted width
-preserves legacy plan shape; inconsistent tile counts or unsupported widths fail validation.
-Acquisition chunk width changes neither CFA/seed coordinates nor development pixels, and does
-not establish transport or device-resource qualification.
+Creates a native RAW development task.
+
+It checks that every CFA phase has a reconstruction kernel and that every kernel neighbourhood is
+available, takes ownership of the packed RAW (without copying where supported), and renders 256-pixel
+output tiles with the fast typed kernel. Development scales each site to its CFA phase's effective white
+level, clips flagged or white-level sites before white balance, and applies the selected highlight mode
+(see `prepareSensorColorDevelopment`).
+
+The RAW numbers are checked in bounded chunks at the start of `run()`, with host yields, so creating the
+task costs only as much as reading the metadata. The task yields to the host at chunk and tile boundaries
+once about 8 ms of work has passed since the last yield, and after the final tile. Yield timing never
+changes the output.
+
+`provider` is `{ yieldControl, onProgress? }`, the same shape as the other native task providers. A bare
+yield function is still accepted in 2.x but is deprecated.
+
+The tile width used at capture is kept when rebuilding the exact packed plan. That width changes neither
+CFA or noise-seed coordinates nor the developed pixels, and says nothing about transport or what a device
+can handle.
 
 ```ts
 export function createNativeRawDevelopmentTask(input: NativeRawDevelopmentInput,
-  yieldControl: (signal:AbortSignal)=>Promise<void>): NativeRawDevelopmentTask;
+  provider: NativeRawDevelopmentProvider | ((signal:AbortSignal)=>Promise<void>)): NativeRawDevelopmentTask;
 ```
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
@@ -23,12 +37,26 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface NativeRawDevelopmentInput {
+  /**
+   * Packed RAW. Ownership passes to the task. On creation its five typed arrays are detached with
+   * `ArrayBuffer.prototype.transfer` (no copy; the caller's arrays become length 0), or copied when
+   * the runtime has no `transfer`. The developed output hands back the same RAW, now owned by the output.
+   */
   raw: NativeRawOutput;
   phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
   colorProfile: ExportSensorColorProfile;
   whiteBalance: "not-required" | "apply-resolved-sensor-gains";
   rendering: SdrRenderingProfile;
-  /** Includes one owned packed RAW copy plus integer output; not caller buffers, process heap or GPU. */
+  /** Highlight handling. `clip` (default): clipped highlights become neutral. `reconstruct`: the documented blend toward neutral. */
+  highlightMode?: RawHighlightMode;
+  /**
+   * Frame-edge handling. `reject` (default): every reconstruction neighbourhood must lie inside the
+   * native RAW frame. `mirror`: a site outside the frame is read from its mirror image (reflect-101,
+   * edge not repeated). This is allowed only when the mirrored site has the same CFA colour, which is
+   * always true for a 2×2 Bayer pattern. Interior pixels are unchanged.
+   */
+  borderHandling?: RawReconstructionBorderHandling;
+  /** Counts the kept packed RAW plus the integer output. It does not count caller buffers, process heap or GPU memory. */
   maximumRetainedPayloadBytes: number;
 }
 ```
@@ -47,6 +75,8 @@ export interface NativeRawDevelopmentOutput {
   height: number;
   integerSamples: Uint8Array | Uint16Array;
   diagnostics: SdrRenderingResult["diagnostics"];
+  highlight: RawHighlightDiagnostics;
+  borderHandling: RawReconstructionBorderHandling;
   outputEncoding: SdrRenderingResult["outputEncoding"];
   rendering: SdrRenderingProfile;
   displayAdaptation: SdrRenderingResult["displayAdaptation"];
@@ -55,6 +85,19 @@ export interface NativeRawDevelopmentOutput {
 }
 ```
 
+## NativeRawDevelopmentProvider
+
+Host callbacks, the same shape as the other native task providers but without a tile reader.
+
+```ts
+export interface NativeRawDevelopmentProvider {
+  /** Must yield to the host event loop, so cancellation and input events can run between tiles. */
+  yieldControl(signal: AbortSignal): Promise<void>;
+  /** Optional callback after each committed 256-pixel output tile. It cannot change the output. */
+  onProgress?(progress: NativeTaskProgress): void;
+}
+```
+
 ## NativeRawDevelopmentTask
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -62,9 +105,27 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface NativeRawDevelopmentTask {
   readonly state: NativeRawTaskState;
+  readonly completedTileCount: number;
+  readonly totalTileCount: number;
   run(): Promise<void>;
   cancel(): void;
   dispose(): void;
   takeOutput(): NativeRawDevelopmentOutput;
 }
 ```
+
+## RawHighlightDiagnostics
+
+RAW saturation handled before white balance. Counts are pixels or samples of the developed output.
+
+```ts
+export interface RawHighlightDiagnostics {
+  mode: RawHighlightMode;
+  /** 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`. */
+  whiteBalanceClippedSampleCount: number;
+  /** `reconstruct`: pixels blended toward neutral. Always 0 for `clip`. */
+  reconstructedPixelCount: number;
+}
+```

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

@@ -0,0 +1,84 @@
+# capture/native-raw-dng.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.
+
+## NATIVE_RAW_DNG_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+NATIVE_RAW_DNG_SCHEMA_VERSION = "1.0.0" as const
+```
+
+## NativeRawDng
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeRawDng {
+  schemaVersion: typeof NATIVE_RAW_DNG_SCHEMA_VERSION;
+  mediaType: "image/dng";
+  bytes: Uint8Array;
+  sha256: string;
+  /** RawDataUniqueID (32 hex digits): the first 128 bits of SHA-256 over a fixed header and the little-endian codes. */
+  rawDataUniqueId: string;
+  uniqueCameraModel: string;
+  /** Stored geometry, levels and colour values exactly as written (rationals as numerator/denominator). */
+  activeArea: { x: number; y: number; width: number; height: number };
+  defaultCrop: { x: number; y: number; width: number; height: number };
+  orientation: number;
+  blackLevels: readonly number[];
+  whiteLevel: number;
+  cfaPattern: readonly number[];
+  colorMatrix1: readonly number[];
+  asShotNeutral: readonly number[];
+  noiseProfile: readonly number[] | null;
+  /** Sites flagged saturated whose code is below WhiteLevel; DNG has no field for them. */
+  unrepresentedSaturationFlagCount: number;
+  source: "packed-native-raw";
+  linearMasterDeclared: false;
+}
+```
+
+## NativeRawDngChannelNoise
+
+Output-referred noise parameters of one CFA channel (see the module notes).
+
+```ts
+export interface NativeRawDngChannelNoise {
+  /** Electrons per output RAW code (system conversion gain divided by any post-ADC digital gain). */
+  conversionGainElectronsPerCode: number;
+  /** Combined RMS read noise, electrons. */
+  readNoiseRmsElectrons: number;
+}
+```
+
+## serializeNativeRawDng
+
+Writes packed native RAW codes as a lossless, uncompressed CFA DNG. The module notes list every tag and
+where its value comes from. The input arrays are copied before the first await.
+
+```ts
+export async function serializeNativeRawDng(input: SerializeNativeRawDngInput): Promise<NativeRawDng>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## SerializeNativeRawDngInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SerializeNativeRawDngInput {
+  /** Packed native RAW. It is read, never taken over or modified. */
+  raw: NativeRawOutput;
+  /** Declared camera→XYZ (D65) colour profile for the RAW's CFA. Native development uses the same profile. */
+  colorProfile: ExportSensorColorProfile;
+  /** Optional NoiseProfile parameters by channel ID. If omitted, no NoiseProfile tag is written. */
+  noise?: Readonly<Record<string, NativeRawDngChannelNoise>>;
+  /** BaselineExposure in EV (exposure value stops). Default 0: the RAW white level maps to display white, as in native development. */
+  baselineExposureEv?: number;
+  /** Optional UTC time of the capture, exactly YYYY-MM-DDTHH:mm:ss.sssZ. If omitted, no date tags are written; the engine never makes up a clock time. */
+  capturedAtUtc?: string;
+}
+```

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

@@ -1,10 +1,10 @@
 # capture/native-raw.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## calculateNativeRawPlan
 
-Full raster/resource/profile admission before callbacks or output allocation; no placeholder plane.
+Plans the task and checks the image size, resources and profiles before any callback or output allocation. No placeholder plane is made.
 
 ```ts
 export function calculateNativeRawPlan(input: NativeRawInput): NativeRawPlan;
@@ -14,7 +14,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## createNativeRawTask
 
-Executes validated EQE/dark/completeness events through the shared reference scalar physics.
+Runs validated per-site events (EQE photo signal, dark signal, charge completeness) through the shared
+reference per-site physics.
+
+Tiles are read and committed one at a time. The task yields to the host at tile boundaries once about
+8 ms of work has passed since the last yield, and after the final tile. It checks for cancellation
+before every tile, after every read and after every yield.
 
 ```ts
 export function createNativeRawTask(input: NativeRawInput,provider: NativeRawProvider): NativeRawTask;
@@ -49,7 +54,7 @@ export type NativeRawExposure = Omit<SimulatedCapture, "schemaVersion" | "planes
 
 ## NativeRawExposureInput
 
-A shooting event and source provenance, not a produced float master or committed RAW frame.
+A shooting event and where its source came from. Not a finished float master or committed RAW frame.
 
 ```ts
 export type NativeRawExposureInput = Omit<SimulatedCaptureInput, "planes" | "source"> & {source:CaptureExposureSource};
@@ -69,14 +74,14 @@ export interface NativeRawInput {
   bindingProfile: NativeRawProducerFrameContext["bindingProfile"];
   exposureWindow?: SensorRawProducerExposureWindowInput;
   maximumOutputBytes: number;
-  /** Optional execution chunk width in native sites, 1–256; omission preserves 256. Not a sampling control. */
+  /** Optional tile width for execution, in native sites, 1–256. Default 256. It does not affect sampling. */
   tileWidth?: number;
 }
 ```
 
 ## NativeRawOutput
 
-Sole-owner row-major arrays. They are not attachable to the bounded SensorRawFrame contract.
+Row-major arrays owned only by the output. They cannot be attached to the bounded SensorRawFrame type.
 
 ```ts
 export interface NativeRawOutput {
@@ -84,8 +89,14 @@ export interface NativeRawOutput {
   codes: Uint16Array;
   blackLevels: Uint16Array;
   digitalSaturationCodes: Uint16Array;
-  /** Bits 0,1,2: physical scalar clamp, pre-ADC clamp, digital saturation respectively. */
+  /** Saturation flags. Bit 0: physical charge clamp; bit 1: pre-ADC clamp; bit 2: digital saturation. */
   saturationFlags: Uint8Array;
+  /**
+   * Effective white (full-saturation) code for each absolute CFA repeat phase, indexed
+   * `phaseY*repeatWidthSites+phaseX`: min(digital saturation, round(black + min(capacity, pre-ADC
+   * saturation)/gain)). See `calculateEffectiveSaturationCode`. A few bytes, not one value per pixel.
+   */
+  effectiveSaturationCodes: Uint16Array;
 }
 ```
 
@@ -102,10 +113,10 @@ export interface NativeRawPlan {
   pixelCount: number;
   outputBytes: number;
   tileCount: number;
-  /** Present only for an explicit execution chunk width. Omission preserves legacy plan shape. */
+  /** Present only when an execution tile width was given. Otherwise the plan keeps its earlier shape. */
   tileWidth?: number;
   upstreamRadiometryVerified: false;
-  seedSchedule: "capture-seed-plus-two-native-index-modulo-2-to-32-v1";
+  seedSchedule: "murmur3-capture-seed-native-index-stream-v2";
 }
 ```
 
@@ -154,7 +165,7 @@ export interface NativeRawTile extends NativeRawTileRequest { sites: readonly Se
 
 ## NativeRawTileRequest
 
-Rectangle is absolute full-native CFA space, before orientation, active crop or output scaling.
+Tile rectangle, in absolute full-sensor CFA coordinates, before orientation, active-area crop or output scaling.
 
 ```ts
 export interface NativeRawTileRequest { captureId: string; frameId: string; x: number; y: number; width: number; height: number }

package/docs/api/capture-packed-sensor-raw.md

@@ -0,0 +1,156 @@
+# capture/packed-sensor-raw.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.
+
+## calculatePackedSensorRawPlan
+
+Validates the request (every array value once) and returns its plan.
+
+```ts
+export function calculatePackedSensorRawPlan(input: PackedSensorRawInput): PackedSensorRawPlan;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PACKED_SENSOR_RAW_LIMITS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PACKED_SENSOR_RAW_LIMITS = Object.freeze({
+  maximumRegionSites: 24_000_000,
+  maximumNativeSites: 0xffffffff,
+  maximumDimension: 65_535,
+  maximumAdcBitDepth: 16,
+  maximumReadNoiseComponents: 16,
+  maximumAdditionalChargeComponents: 8
+})
+```
+
+## PACKED_SENSOR_RAW_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PACKED_SENSOR_RAW_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## PackedSensorAdditionalChargeComponent
+
+One additional stored-charge component, realized after photo and dark charge in declaration order.
+
+```ts
+export interface PackedSensorAdditionalChargeComponent {
+  componentId: string;
+  /** `poisson` draws from the charge stream; `deterministic-expected-electron-equivalent` adds the expectation. */
+  model: SensorAdditionalChargeSamplingModel;
+  /** Expected electrons per region site, row-major. Finite, ≥ 0. */
+  expectedElectrons: Float32Array | Float64Array;
+}
+```
+
+## PackedSensorFixedPatternNoise
+
+Optional fixed-pattern noise for a packed region. The colour-sampling site of native site (X, Y) is
+(X + siteOrigin.x, Y + siteOrigin.y); the pattern is seeded from those coordinates, as in
+`calculateSensorFixedPatternSite`.
+
+```ts
+export interface PackedSensorFixedPatternNoise {
+  profile: SensorFixedPatternNoiseProfile;
+  /** Must equal `profile.colorSamplingProfileId`. */
+  colorSamplingProfileId: string;
+  siteOrigin: { x: number; y: number };
+}
+```
+
+## PackedSensorRawDiagnostics
+
+Per-region saturation and clamp counts, as in the per-site readout diagnostics.
+
+```ts
+export interface PackedSensorRawDiagnostics {
+  physicalSaturationSiteCount: number;
+  preAdcSaturationSiteCount: number;
+  digitalSaturationSiteCount: number;
+  lowerClampSiteCount: number;
+}
+```
+
+## PackedSensorRawInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PackedSensorRawInput {
+  schemaVersion: typeof PACKED_SENSOR_RAW_SCHEMA_VERSION;
+  /** Full native raster. Site seeds use the absolute index `(region.y + row) * nativeWidth + region.x + column`. */
+  nativeWidth: number;
+  nativeHeight: number;
+  /** Region of the native raster to simulate, in native sites. */
+  region: { x: number; y: number; width: number; height: number };
+  /** The committed capture's noise seed (`capture.noise.seedUint32`). */
+  captureSeedUint32: number;
+  /** Expected photo-generated electrons per region site (EQE and local exposure applied), row-major. Finite, ≥ 0. */
+  photoElectrons: Float32Array | Float64Array;
+  /** Expected dark electrons per region site, row-major. Finite, ≥ 0. */
+  darkElectrons: Float32Array | Float64Array;
+  /** Physical charge storage capacity in electrons, the same at every site. */
+  physicalChargeCapacityElectrons: number;
+  readoutProfile: SensorReadoutConversionProfile;
+  regimeId: string;
+  /** Optional (2.0). */
+  fixedPatternNoise?: PackedSensorFixedPatternNoise;
+  /** Optional (2.0), at most 8. */
+  additionalChargeComponents?: readonly PackedSensorAdditionalChargeComponent[];
+}
+```
+
+## PackedSensorRawPlan
+
+Validated plan. Arrays are borrowed, not copied.
+
+```ts
+export interface PackedSensorRawPlan {
+  nativeWidth: number;
+  nativeHeight: number;
+  region: Readonly<{ x: number; y: number; width: number; height: number }>;
+  siteCount: number;
+  captureSeedUint32: number;
+  physicalChargeCapacityElectrons: number;
+  readout: ResolvedSensorReadoutRegime;
+  noiseModel: typeof SENSOR_RAW_PRODUCER_NOISE_MODEL;
+  seedSchedule: "murmur3-capture-seed-native-index-stream-v2";
+  /** Largest expected photo and dark electron counts in the region (before fixed-pattern factors). */
+  maximumPhotoElectrons: number;
+  maximumDarkElectrons: number;
+  /** Parsed fixed-pattern profile and colour-site origin, or null. */
+  fixedPatternNoise: Readonly<{ profile: SensorFixedPatternNoiseProfile; siteOrigin: Readonly<{ x: number; y: number }> }> | null;
+  /** Additional components (identity, model and largest expectation); their arrays stay on the input. */
+  additionalChargeComponents: readonly Readonly<{ componentId: string; model: SensorAdditionalChargeSamplingModel; maximumExpectedElectrons: number }>[];
+}
+```
+
+## PackedSensorRawResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PackedSensorRawResult {
+  plan: PackedSensorRawPlan;
+  /** RAW codes, row-major over the region. */
+  codes: Uint16Array;
+  diagnostics: PackedSensorRawDiagnostics;
+}
+```
+
+## simulatePackedSensorRaw
+
+Synchronous float64 reference for a bounded region. Use the image-kernel accelerator for large
+regions, host yields or the `webgpu-f32` backend.
+
+```ts
+export function simulatePackedSensorRaw(input: PackedSensorRawInput): PackedSensorRawResult;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-photographic-export.md

@@ -1,10 +1,10 @@
 # capture/photographic-export.ts public contracts
 
-Package **1.5.0**, root API **1.5.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## calculateProcessedSensorRaw
 
-Reconstruct exact attached RAW, develop color/WB once, correct, orient/crop and encode SDR; no file/display IO.
+Reconstructs the exact attached RAW, develops colour and WB once, corrects, orients and crops, and encodes SDR. No file or display I/O.
 
 ```ts
 export function calculateProcessedSensorRaw(input: ProcessedSensorRawInput): CalculationResult<ProcessedSensorRawResult>;
@@ -14,24 +14,24 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## createPhotographicExportPair
 
-Serialize one authoritative RAW capture to a lossless uncompressed CFA DNG and an independently
-packed baseline JPEG. Shared metadata comes from the committed capture; orientation/WB/rendering
-never rewrite native RAW codes.
+Writes one RAW capture as a lossless, uncompressed CFA DNG and a separately encoded baseline JPEG.
+Shared metadata comes from the committed capture. Orientation, WB and rendering never rewrite the
+native RAW codes.
 
-Paired export preserves one revalidated native post-ADC RAW frame for DNG and develops that same
-frame through explicit reconstruction, approximate sensor-channel color/WB and SDR policy for JPEG.
-File identity and RAW data identity are distinct. Hashing is asynchronous; input data is copied
-before the first await. Full-native execution is limited to 4096 sites.
+The DNG keeps one revalidated native RAW frame (after the ADC) unchanged. The JPEG develops that same
+frame through explicit reconstruction, an approximate sensor-channel colour and WB conversion, and SDR
+rendering. File identity and RAW data identity are separate. Hashing is asynchronous; input data is
+copied before the first await. The full sensor is limited to 4096 sites.
 
 ```ts
-export async function createPhotographicExportPair(input: PhotographicExportInput): Promise<PhotographicExportPair>;
+export async function createPhotographicExportPair(input: PhotographicExportInput, options: PhotographicExportOptions = {}): Promise<PhotographicExportPair>;
 ```
 
 This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
 
 ## ExportSensorColorProfile
 
-Explicit approximation of normalized camera-channel -> scene XYZ/D65, never inferred from RGB/CFA names.
+Explicit, approximate conversion from normalized camera channels to scene XYZ (D65). Never guessed from RGB or CFA channel names.
 
 ```ts
 export interface ExportSensorColorProfile {
@@ -50,7 +50,7 @@ export interface ExportSensorColorProfile {
 
 ## parseExportSensorColorProfile
 
-Validates independently supplied numeric profile evidence and binds the approximation to the exact CFA profile.
+Validates the separately supplied numeric colour-profile evidence, and ties the approximate profile to the exact CFA profile.
 
 ```ts
 export function parseExportSensorColorProfile(value: unknown): ExportSensorColorProfile;
@@ -60,7 +60,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePhotographicExportInput
 
-Adds file metadata/encoding validation to the shared processed RAW policy.
+Adds file metadata and encoding checks to the shared RAW processing settings.
 
 ```ts
 export function parsePhotographicExportInput(value: unknown): PhotographicExportInput;
@@ -70,11 +70,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseProcessedSensorRawInput
 
-Revalidates one attached RAW snapshot and explicit processing policy.
-Crop sampling and reconstruction coverage fail here before
-per-pixel execution. Successful parsing does not establish kernel edge support,
-correction support or container encoding readiness; those retain execution
-checks. Input is copied; no file or display backend runs.
+Revalidates one attached RAW snapshot and the explicit processing settings.
+
+Crop sampling and reconstruction coverage problems fail here, before per-pixel work. Passing this
+check does not prove kernel support at the edges, correction support or that the file can be encoded;
+those are still checked during execution. The input is copied. No file or display code runs.
 
 ```ts
 export function parseProcessedSensorRawInput(value: unknown): ProcessedSensorRawInput;
@@ -82,6 +82,18 @@ export function parseProcessedSensorRawInput(value: unknown): ProcessedSensorRaw
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PHOTOGRAPHIC_EXPORT_PIPELINE_VERSION
+
+Version of the RAW and processed pipeline, recorded in XMP.
+
+0.2.0: development scales to the effective white level, handles saturation, and fixes WB for colour
+matrices that are not white-normalized. DNG output fixes WhiteLevel, AsShotNeutral and BlackLevel/CFA
+phase, and adds the DNG 1.4 tags ForwardMatrix1, BaselineExposure, NoiseProfile and AnalogBalance.
+
+```ts
+PHOTOGRAPHIC_EXPORT_PIPELINE_VERSION = "0.2.0" as const
+```
+
 ## PHOTOGRAPHIC_EXPORT_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -92,7 +104,7 @@ PHOTOGRAPHIC_EXPORT_SCHEMA_VERSION = "0.1.0" as const
 
 ## PhotographicExportInput
 
-Optional explicit exporter boundary; no files, clocks, randomness, network or encoder dependency.
+Optional export settings. The engine uses no files, clocks, randomness, network or external encoder.
 
 ```ts
 export interface PhotographicExportInput {
@@ -101,18 +113,31 @@ export interface PhotographicExportInput {
   whiteBalance: "not-required" | "apply-resolved-sensor-gains";
   rendering: SdrRenderingProfile;
   metadata: Omit<CaptureExportMetadataInput, "capture">;
-  /** Caller-declared public scene/version, explicitly bound to the committed scene state. */
+  /** Public scene ID and version declared by the caller. They must match the committed scene state. */
   sceneProfile: { id: string; version: string; sceneStateId: string };
-  /** JPEG constant quantization step 1..255, not an emulated manufacturer's 'quality' scale. */
+  /** JPEG constant quantization step, 1..255. It is not an imitation of a manufacturer's "quality" scale. */
   jpegQuantizationStep: number;
-  /** Optional native-optical post-color correction; JPEG only, RAW records informational intent. */
+  /** Optional lens correction in native optical coordinates, applied after colour. JPEG only; the RAW records it as information. */
   correction?: CaptureCorrectedSdrInput["correction"];
+  /** How RAW highlights are handled before WB; default `clip`. See `prepareSensorColorDevelopment`. */
+  highlightMode?: RawHighlightMode;
+}
+```
+
+## PhotographicExportOptions
+
+Options for {@link createPhotographicExportPair}.
+
+```ts
+export interface PhotographicExportOptions {
+  /** Aborting rejects with a domain error at the next step. No partial pair is returned. */
+  signal?: AbortSignal;
 }
 ```
 
 ## PhotographicExportPair
 
-Owned byte arrays are mutable; identities/hashes refer to the exact bytes returned at creation.
+The byte arrays belong to the caller and can be changed. IDs and hashes refer to the exact bytes as first returned.
 
 ```ts
 export interface PhotographicExportPair {
@@ -125,10 +150,12 @@ export interface PhotographicExportPair {
   source: CalculationResult<RawFrameReconstruction>;
   rendering: CalculationResult<SdrRenderingResult>;
   nativeDefaultCrop: RasterRect;
-  /** Derived JPEG rectangle in the declared oriented output; never replaces the RAW default crop. */
+  /** The JPEG's rectangle in the oriented output. It never replaces the RAW's default crop. */
   processedOutputView: { rect: RasterRect; pixelWidth: number; pixelHeight: number };
   correction: CalculationResult<CaptureCorrectedSdrResult> | null;
   rawCorrectionIntent: CalculationResult<ResolvedLensCorrectionPlan> | null;
+  /** RAW saturation handled before WB in the JPEG development. */
+  highlight: RawHighlightDiagnostics;
   imageDataPairing: "jpeg-generated-from-exact-attached-raw";
   dng: { mediaType: "image/dng"; bytes: Uint8Array; sha256: string };
   jpeg: { mediaType: "image/jpeg"; bytes: Uint8Array; sha256: string };
@@ -136,22 +163,31 @@ export interface PhotographicExportPair {
 }
 ```
 
+## PROCESSED_SENSOR_RAW_MODEL_VERSION
+
+Version of the `processed-sensor-raw-sdr` model (0.2.0: scaling to effective white, saturation and WB fixes).
+
+```ts
+PROCESSED_SENSOR_RAW_MODEL_VERSION = "0.2.0" as const
+```
+
 ## ProcessedSensorRawInput
 
-Explicit post-ADC RAW development policy shared by preview and file output.
+Explicit RAW development settings (after the ADC), shared by the preview and the file output.
 
 ```ts
 export type ProcessedSensorRawInput = Pick<PhotographicExportInput,
-  "reconstruction" | "colorProfile" | "whiteBalance" | "rendering" | "correction">;
+  "reconstruction" | "colorProfile" | "whiteBalance" | "rendering" | "correction" | "highlightMode">;
 ```
 
 ## ProcessedSensorRawResult
 
-Owned derived preview/JPEG processing record for the exact attached native RAW.
-Child reconstruction/color/WB/correction/rendering results expose their input
-and output domains and independent clipping/cost diagnostics. The output view is
-oriented/cropped SDR, while the native default crop and physical capture history
-remain unchanged. Returned arrays are pre-file pixels, not a lossy JPEG decode.
+Processing record for the preview and JPEG, derived from the exact attached native RAW.
+
+Each step (reconstruction, colour, WB, correction, rendering) reports its input and output domains and
+its own clipping and cost diagnostics. The output view is oriented and cropped SDR. The native default
+crop and the physical capture history are unchanged. The returned arrays are the pixels before file
+encoding, not a decoded (lossy) JPEG.
 
 ```ts
 export interface ProcessedSensorRawResult {
@@ -168,5 +204,7 @@ export interface ProcessedSensorRawResult {
   processedOutputView: PhotographicExportPair["processedOutputView"];
   correction: CalculationResult<CaptureCorrectedSdrResult> | null;
   rawCorrectionIntent: CalculationResult<ResolvedLensCorrectionPlan> | null;
+  /** RAW saturation handled before WB, over the developed image. */
+  highlight: RawHighlightDiagnostics;
 }
 ```