@photivra/engine 1.5.0 → 2.0.0

package/docs/api/output-print-region-statistics.md

@@ -1,10 +1,10 @@
 # output/print-region-statistics.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.
 
 ## calculatePrintRegionDifference
 
-Measure registered processing changes; residual is not automatically compression/noise.
+Measures how processing changed aligned samples. The residual is not automatically compression or noise.
 
 ```ts
 export function calculatePrintRegionDifference(value: PrintRegionDifferenceInput): CalculationResult<PrintRegionStatisticsAssessment<PrintRegionDifferenceInput, PrintRegionDifferenceMeasurement>>;
@@ -14,7 +14,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculatePrintRegionNoise
 
-Measure n-1 per-site temporal sample variance, independently of scene spatial texture.
+Measures the sample variance over time at each site (n-1 denominator), separately from spatial scene texture.
 
 ```ts
 export function calculatePrintRegionNoise(value: PrintRegionNoiseInput): CalculationResult<PrintRegionStatisticsAssessment<PrintRegionNoiseInput, PrintRegionNoiseMeasurement>>;
@@ -24,7 +24,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## MAX_PRINT_REGION_STATISTICS_SAMPLES
 
-Maximum scalar samples across every frame/reference in one request.
+Maximum number of single-channel samples across all frames and references in one request.
 
 ```ts
 MAX_PRINT_REGION_STATISTICS_SAMPLES = MAX_PRINT_DETAIL_REGION_SAMPLES
@@ -32,7 +32,7 @@ MAX_PRINT_REGION_STATISTICS_SAMPLES = MAX_PRINT_DETAIL_REGION_SAMPLES
 
 ## parsePrintRegionDifferenceInput
 
-Parse/copy an untrusted paired scalar ROI request.
+Parses and copies an untrusted request that pairs two single-channel ROIs.
 
 ```ts
 export function parsePrintRegionDifferenceInput(v: unknown): PrintRegionDifferenceInput;
@@ -42,7 +42,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePrintRegionNoiseInput
 
-Parse/copy an untrusted repeat-capture ensemble with a total scalar work bound.
+Parses and copies an untrusted set of repeat captures, with a limit on the total number of samples.
 
 ```ts
 export function parsePrintRegionNoiseInput(v: unknown): PrintRegionNoiseInput;
@@ -52,7 +52,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PRINT_REGION_STATISTICS_MODEL_VERSION
 
-Independent of the root distribution and coherent-detail protocol.
+Version of this protocol. Independent of the package version and of the print-detail protocol.
 
 ```ts
 PRINT_REGION_STATISTICS_MODEL_VERSION = "0.1.0" as const
@@ -60,7 +60,7 @@ PRINT_REGION_STATISTICS_MODEL_VERSION = "0.1.0" as const
 
 ## PrintRegionDifferenceInput
 
-Compare identical sample sites through processing, without mixing noise draws.
+Compares the same sample sites before and after processing, from the same noise draw.
 A known range is a declared reference signal range, never a clipping threshold.
 
 ```ts
@@ -83,7 +83,7 @@ export interface PrintRegionDifferenceMeasurement {
   meanSignedDifferenceRelativeLuminance: number;
   rmsDifferenceRelativeLuminance: number;
   maximumAbsoluteDifferenceRelativeLuminance: number;
-  /** Null unless the caller supplied a reference range; not a halo classifier. */
+  /** Null unless the caller supplied a reference range. It does not classify halos. */
   rangeExcursions: {
     beforeBelowRangeCount: number;
     beforeAboveRangeCount: number;
@@ -99,8 +99,8 @@ export interface PrintRegionDifferenceMeasurement {
 
 ## PrintRegionNoiseInput
 
-Sample statistics at registered sites over independently acquired repeats.
-Stationarity/independence are declarations; a single frame is never a noise ensemble.
+Statistics at aligned sites across separately acquired repeat captures.
+Stationarity and independence are declared by the caller. A single frame is never treated as a noise sample set.
 
 ```ts
 export interface PrintRegionNoiseInput {
@@ -124,7 +124,7 @@ export interface PrintRegionNoiseMeasurement {
   /** Mean of per-site sample variances with n-1 denominator, in squared linear units. */
   meanTemporalSampleVarianceRelativeLuminanceSquared: number;
   temporalRmsRelativeLuminance: number;
-  /** Separately retained so scene texture/fixed pattern is not relabelled temporal noise. */
+  /** Kept separate so scene texture and fixed-pattern variation are not mislabelled as temporal noise. */
   perSiteMeansRelativeLuminance: readonly number[];
   perSiteSampleVariancesRelativeLuminanceSquared: readonly number[];
 }
@@ -132,7 +132,7 @@ export interface PrintRegionNoiseMeasurement {
 
 ## PrintRegionRaster
 
-Exact, unwarped scalar linear ROI; sample and hash verification remains external.
+An exact, unwarped, single-channel linear region of interest (ROI). Checking the samples and their hash is up to the caller.
 
 ```ts
 export interface PrintRegionRaster {
@@ -145,7 +145,7 @@ export interface PrintRegionRaster {
 
 ## PrintRegionStatisticsAssessment
 
-Measurements remain diagnostic. No physical-noise calibration or print verdict.
+The measurements are diagnostics only. They are not a physical noise calibration or a print verdict.
 
 ```ts
 export interface PrintRegionStatisticsAssessment<TInput, TMeasurement> {

package/docs/api/output-sdr-rendering.md

@@ -1,11 +1,12 @@
 # output/sdr-rendering.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.
 
 ## calculateSdrRendering
 
 Standalone SDR rendering: rendering exposure → tone → gamut → sRGB transfer → quantization.
-No physical capture, metering, WB/color/correction integration or display adaptation runs.
+No physical capture, metering, white balance, colour conversion, lens correction or display
+adaptation runs.
 
 ```ts
 export function calculateSdrRendering(input: SdrRenderingInput): CalculationResult<SdrRenderingResult>;
@@ -15,7 +16,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSdrRenderingInput
 
-Validates declared image state and a bounded finite inline raster; never resolves WB/color.
+Validates the declared image state and a bounded, finite, inline image. It never applies white balance or colour conversion.
 
 ```ts
 export function parseSdrRenderingInput(value: unknown): SdrRenderingInput;
@@ -25,7 +26,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseSdrRenderingProfile
 
-Validates every explicit rendering/encoding policy; unknown HDR/display modes fail.
+Validates a rendering and encoding profile. Unknown HDR or display modes are rejected.
 
 ```ts
 export function parseSdrRenderingProfile(value: unknown): SdrRenderingProfile;
@@ -33,6 +34,15 @@ export function parseSdrRenderingProfile(value: unknown): SdrRenderingProfile;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## SDR_RENDERING_MODEL_VERSION
+
+Version of the `generic-sdr-rendering-reference` model. 0.2.0 added luminance tone curves and fixed
+round-to-nearest, ties up (`Math.round`; the old `Math.floor(x+.5)` rounded 0.49999999999999994 up).
+
+```ts
+SDR_RENDERING_MODEL_VERSION = "0.2.0" as const
+```
+
 ## SDR_RENDERING_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -43,7 +53,7 @@ SDR_RENDERING_SCHEMA_VERSION = "0.1.0" as const
 
 ## SdrRenderingInput
 
-Only an explicitly color-transformed, co-sited linear-sRGB/D65 raster is accepted.
+Only linear-sRGB/D65 data that has been explicitly colour-transformed, with all three channels at each pixel, is accepted.
 
 ```ts
 export interface SdrRenderingInput {
@@ -62,7 +72,7 @@ export interface SdrRenderingInput {
 
 ## SdrRenderingProfile
 
-First-party rendering choices, independent of physical exposure and display calibration.
+Rendering choices made by the engine user. They are independent of physical exposure and display calibration.
 
 ```ts
 export interface SdrRenderingProfile {
@@ -70,7 +80,9 @@ export interface SdrRenderingProfile {
   profileId: string;
   profileVersion: string;
   renderingExposureEv: number;
-  toneCurve: "identity" | "positive-reinhard-per-channel";
+  toneCurve: SdrToneCurve;
+  /** Present exactly for `extended-reinhard-luminance` ({whiteLuminance}) and `naka-rushton-luminance`. */
+  toneCurveParameters?: SdrToneCurveParameters;
   gamutHandling: "clip-components" | "reject-out-of-range";
   outputDynamicRange: "sdr";
   transferFunction: "srgb";
@@ -113,10 +125,40 @@ export interface SdrRenderingResult {
     toneChangedSampleCount: number;
     gamutClippedLowSampleCount: number;
     gamutClippedHighSampleCount: number;
-    /** Upstream full-well/ADC/RAW saturation is unavailable, never inferred from output. */
-    captureSaturation: "not-consumed";
+    /**
+     * `not-consumed`: no upstream saturation data (full well, ADC or RAW) is available, and it is never
+     * guessed from the output.
+     * `consumed-in-raw-development`: RAW development already clipped or reconstructed flagged and
+     * white-level samples before white balance (see its highlight diagnostics).
+     */
+    captureSaturation: "not-consumed" | "consumed-in-raw-development";
   };
-  /** Platform color management follows this encoded output; no actual display is assessed. */
+  /** Describes the encoded output for the platform's colour management. No real display is assessed. */
   displayAdaptation: { kind: "external-platform"; applied: false; displayCapabilities: "unknown" };
 }
 ```
+
+## SdrToneCurve
+
+Tone curves. A per-channel curve acts on each exposed component separately. A luminance curve
+scales all three components of a pixel by f(L)/L, where L is the linear-sRGB/D65 relative
+luminance, so the colour (chromaticity) is kept before gamut handling.
+- `identity`: f(x)=x.
+- `positive-reinhard-per-channel`: f(x)=x/(1+x) for x>0 (Reinhard et al. 2002, eq. 3), per channel.
+- `extended-reinhard-luminance`: f(L)=L(1+L/Lw²)/(1+L) (Reinhard et al. 2002, eq. 4); L=Lw maps to 1.
+- `naka-rushton-luminance`: f(L)=g(L)/g(Lw), g(L)=Lⁿ/(Lⁿ+σⁿ) (Naka & Rushton 1966; Reinhard & Devlin
+  2005): a sigmoid in log luminance with contrast n and mid-response σ, i.e. a film-like S-curve.
+
+```ts
+export type SdrToneCurve = "identity" | "positive-reinhard-per-channel" | "extended-reinhard-luminance" | "naka-rushton-luminance";
+```
+
+## SdrToneCurveParameters
+
+Required only by luminance curves; all values are relative linear luminance after rendering exposure.
+
+```ts
+export type SdrToneCurveParameters =
+  | { whiteLuminance: number }
+  | { exponent: number; semiSaturation: number; whiteLuminance: number };
+```

package/docs/api/output-subject-framing-crop.md

@@ -1,15 +1,14 @@
 # output/subject-framing-crop.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.
 
 ## calculateSubjectFramingCrop
 
-Calculates the same-aspect-ratio crop needed for a subject to occupy a
-requested fraction of frame height.
+Calculates the crop (keeping the aspect ratio) that makes a subject fill a
+requested fraction of the frame height.
 
-This calculation assumes a centered/positionable crop with enough spatial
-margin around the subject. It does not validate subject position against
-image edges.
+It assumes the crop can be centred or moved freely, with enough room around
+the subject. It does not check the subject's position against the image edges.
 
 ```ts
 export function calculateSubjectFramingCrop(

package/docs/api/processing-demosaic.md

@@ -0,0 +1,120 @@
+# processing/demosaic.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.
+
+## AhdDemosaicInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AhdDemosaicInput {
+  plane: CfaMosaicPlane;
+  /** CFA channel ids of the red, green and blue sites; output order is red, green, blue. */
+  channelRoles: { red: string; green: string; blue: string };
+  /**
+   * Camera-linear RGB → CIE XYZ, used only for the homogeneity metric (in CIELAB). Default: the
+   * sRGB/D65 matrix, so the plane is treated as linear sRGB for the metric. Output values are never
+   * transformed.
+   */
+  cameraToXyz?: ColorMatrix3x3;
+  maximumWorkingBytes?: number;
+}
+```
+
+## AhdDemosaicOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AhdDemosaicOutput extends ProcessingRgbImage {
+  /** Per pixel: 0 horizontal, 1 vertical, 2 equal homogeneity (average of both). */
+  direction: Uint8Array;
+  provenance: ProcessingProvenance;
+}
+```
+
+## CfaMosaicPlane
+
+A single-channel linear CFA mosaic in absolute native site coordinates (row-major, +Y down).
+
+```ts
+export interface CfaMosaicPlane {
+  width: number;
+  height: number;
+  captureModeId: string;
+  /** Periodic mosaic anchored at site (0, 0) of this plane. */
+  colorSamplingProfile: SensorColorSamplingProfile;
+  /** Linear values, e.g. black-subtracted normalized RAW or merged HDR radiance. */
+  samples: Float32Array;
+}
+```
+
+## CfaPlaneReconstructionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CfaPlaneReconstructionInput {
+  plane: CfaMosaicPlane;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+  /** Default `reject`: every neighbourhood must lie inside the plane. */
+  borderHandling?: RawReconstructionBorderHandling;
+  /** Output region in plane coordinates; default the whole plane. */
+  region?: { x: number; y: number; width: number; height: number };
+  maximumWorkingBytes?: number;
+}
+```
+
+## CfaPlaneReconstructionOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CfaPlaneReconstructionOutput {
+  width: number;
+  height: number;
+  region: { x: number; y: number; width: number; height: number };
+  channelIds: readonly string[];
+  /** Interleaved `channelIds.length` channels, row-major over the region. */
+  data: Float32Array;
+  borderHandling: RawReconstructionBorderHandling;
+  provenance: ProcessingProvenance;
+}
+```
+
+## createAhdDemosaicTask
+
+Adaptive homogeneity-directed (AHD) demosaicing after Hirakawa & Parks, IEEE TIP 14(3), 2005:
+1. green is interpolated separately along rows and columns with the 5-tap directional filter
+   [−1/4, 1/2, 1/2, 1/2, −1/4] (bilinear green plus the own-channel second difference);
+2. red and blue are filled from bilinearly interpolated colour differences (R−G, B−G) against each
+   directional green, giving two full-colour candidates;
+3. both candidates are converted to CIELAB. At each pixel, the homogeneity is the number of
+   4-neighbours within adaptive luminance and chrominance tolerances ε_L, ε_C. Each tolerance is the
+   smaller of the two directions' largest differences along their own direction;
+4. homogeneity is summed over 3×3, and the more homogeneous candidate is chosen (a tie averages
+   both).
+The paper's optional iterative median step for reducing artifacts is not applied. Mirrored
+(reflect-101) borders keep each site's Bayer channel. The method is non-linear: the output is not a
+linear function of the mosaic.
+
+```ts
+export function createAhdDemosaicTask(input: AhdDemosaicInput, provider: ProcessingProvider): ProcessingTask<AhdDemosaicOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createCfaPlaneReconstructionTask
+
+Runs explicit linear reconstruction kernels, one per CFA phase, over a typed CFA plane.
+- With `mirror` borders, a site outside the plane is read from its mirrored (reflect-101) position.
+  This is accepted only if the mirrored site has the same CFA channel, which is always true for a
+  2×2 Bayer pattern.
+- With `reject`, out-of-plane reads throw (fail closed), like the reference resolver.
+Values are linear and signed. No clamping, white balance or colour transform is applied.
+
+```ts
+export function createCfaPlaneReconstructionTask(input: CfaPlaneReconstructionInput, provider: ProcessingProvider): ProcessingTask<CfaPlaneReconstructionOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/processing-denoise.md

@@ -0,0 +1,148 @@
+# processing/denoise.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.
+
+## BilateralFilterInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BilateralFilterInput {
+  image: ProcessingRgbImage;
+  spatialSigmaPixels: number;
+  /** Range σ in the units of the image values. */
+  rangeSigma: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## createBilateralFilterTask
+
+Brute-force bilateral filter (window radius ⌈3σ_s⌉, reflect-101 borders).
+
+```ts
+export function createBilateralFilterTask(input: BilateralFilterInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createNonLocalMeansTask
+
+Non-local means (Buades, Coll & Morel 2005), offset-major with box-filtered patch distances.
+
+```ts
+export function createNonLocalMeansTask(input: NonLocalMeansInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createSyntheticFilmGrainTask
+
+Adds deterministic synthetic grain:
+1. Unit-variance Gaussian white noise per pixel. It is seeded by the absolute pixel index, so tiling
+   never changes it.
+2. Optionally blurred by a Gaussian with σ = grain size, then renormalized to unit variance.
+3. Scaled by a(v) = intensity·2√(v(1 − v)): zero at black and white, `intensity` at mid-grey.
+4. Clipped to [0, 1].
+It is labelled synthetic and aesthetic. It is never a film model.
+
+```ts
+export function createSyntheticFilmGrainTask(input: SyntheticFilmGrainInput, provider: ProcessingProvider): ProcessingTask<SyntheticFilmGrainOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createUnsharpMaskTask
+
+Unsharp masking: in + amount·(in − G_σ ⊗ in) where the detail exceeds the threshold.
+
+```ts
+export function createUnsharpMaskTask(input: UnsharpMaskInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NonLocalMeansInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NonLocalMeansInput {
+  image: ProcessingRgbImage;
+  /** Filtering parameter h (image units). */
+  filteringParameter: number;
+  /** Known noise standard deviation σ (image units); default 0. */
+  noiseStandardDeviation?: number;
+  /** Patch radius f (patch (2f+1)²); default 1. */
+  patchRadius?: number;
+  /** Search-window radius r ((2r+1)² candidates); default 5. */
+  searchRadius?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## ProcessedRgbImage
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ProcessedRgbImage extends ProcessingRgbImage {
+  provenance: ProcessingProvenance;
+}
+```
+
+## SYNTHETIC_FILM_GRAIN_STREAM_ID
+
+Random-stream id for synthetic grain. Different from every RAW charge, read-noise and fixed-pattern stream.
+
+```ts
+SYNTHETIC_FILM_GRAIN_STREAM_ID = 64 as const
+```
+
+## SyntheticFilmGrainInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SyntheticFilmGrainInput {
+  /** Display-referred (encoded) RGB with values in [0, 1]. */
+  image: ProcessingRgbImage;
+  /** uint32 seed; equal seeds reproduce the grain exactly. */
+  seedUint32: number;
+  /** Grain standard deviation at mid-grey (value 0.5), in encoded units. */
+  intensity: number;
+  /** Spatial correlation σ of the grain in pixels; 0 = per-pixel white grain. Default 0.7. */
+  grainSizePixels?: number;
+  /** `monochrome` (default) adds one grain field to all channels; `per-channel` uses three. */
+  mode?: "monochrome" | "per-channel";
+  maximumWorkingBytes?: number;
+}
+```
+
+## SyntheticFilmGrainOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SyntheticFilmGrainOutput extends ProcessedRgbImage {
+  /** Always true: the grain is an aesthetic texture, not a physical film model. */
+  syntheticAesthetic: true;
+  physicalFilmModel: false;
+  clippedSampleCount: number;
+}
+```
+
+## UnsharpMaskInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface UnsharpMaskInput {
+  image: ProcessingRgbImage;
+  radiusSigmaPixels: number;
+  amount: number;
+  /** Detail magnitude below which a component is left unchanged; default 0. */
+  threshold?: number;
+  maximumWorkingBytes?: number;
+}
+```

package/docs/api/processing-focus-stacking.md

@@ -0,0 +1,41 @@
+# processing/focus-stacking.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.
+
+## createFocusStackTask
+
+Laplacian-energy focus stacking with Laplacian-pyramid blending.
+
+```ts
+export function createFocusStackTask(input: FocusStackInput, provider: ProcessingProvider): ProcessingTask<FocusStackOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## FocusStackInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusStackInput {
+  /** Registered frames of one scene, ordered by focus distance (any consistent order). */
+  frames: readonly ProcessingRgbImage[];
+  /** σ (pixels) of the Gaussian window averaging the squared Laplacian; default 2. */
+  sharpnessSigmaPixels?: number;
+  /** Pyramid levels for seam-free blending; default down to a 1-pixel side (at most 10). */
+  pyramidLevels?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## FocusStackOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusStackOutput extends ProcessingRgbImage {
+  /** Index of the sharpest frame per pixel (the blending selection). */
+  selectedFrameIndex: Uint8Array;
+  provenance: ProcessingProvenance;
+}
+```

package/docs/api/processing-hdr.md

@@ -0,0 +1,113 @@
+# processing/hdr.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.
+
+## createHdrBracketMergeTask
+
+Noise-optimal merge of linear RAW exposure brackets into a scene-linear photo-electron rate.
+
+```ts
+export function createHdrBracketMergeTask(input: HdrBracketMergeInput, provider: ProcessingProvider): ProcessingTask<HdrBracketMergeOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createHdrImageEncodingTask
+
+Converts linear RGB to unclipped float32 linear BT.2020 (relative values, no transfer function or quantization).
+
+```ts
+export function createHdrImageEncodingTask(input: HdrImageEncodingInput, provider: ProcessingProvider): ProcessingTask<HdrImageEncodingOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## HdrBracketFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketFrame {
+  exposureTimeSeconds: number;
+  /** Linear RAW codes, one per sample. */
+  codes: Uint16Array | Float32Array;
+  blackLevelCode: number;
+  /** Codes at or above this level are saturated and excluded. */
+  whiteLevelCode: number;
+  /** Optional per-sample flags. Non-zero excludes the sample (for example physical saturation before the ADC). */
+  saturationFlags?: Uint8Array;
+  /** System conversion gain K, electrons per code (includes the frame's ISO gain). */
+  conversionGainElectronsPerCode: number;
+  /** RMS read noise in electrons for this frame's readout regime. */
+  readNoiseElectrons: number;
+}
+```
+
+## HdrBracketMergeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketMergeInput {
+  /** Samples per frame (e.g. width·height for a mosaic, width·height·3 for RGB). */
+  sampleCount: number;
+  frames: readonly HdrBracketFrame[];
+  /** Variance reweighting iterations after the shot-noise-limited start; default 2. */
+  iterations?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## HdrBracketMergeOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketMergeOutput {
+  /** Scene-linear photo-electron rate per sample, e⁻/s (relative scene radiance; not absolute). */
+  radianceElectronsPerSecond: Float32Array;
+  /** Model standard deviation of each estimate, e⁻/s. */
+  standardDeviationElectronsPerSecond: Float32Array;
+  /** Frames that contributed; 0 marks a sample saturated in every frame (value is a lower bound). */
+  contributingFrameCount: Uint8Array;
+  saturatedInAllFramesCount: number;
+  provenance: ProcessingProvenance;
+}
+```
+
+## HdrImageEncodingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrImageEncodingInput {
+  image: ProcessingRgbImage;
+  inputColorSpace: ProcessingLinearColorSpace;
+  transfer: HdrTransfer;
+  maximumWorkingBytes?: number;
+}
+```
+
+## HdrImageEncodingOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrImageEncodingOutput {
+  width: number;
+  height: number;
+  colorSpace: "rec2020";
+  transfer: HdrTransfer;
+  /** Interleaved linear BT.2020 RGB (relative, unclipped). */
+  linear: Float32Array;
+  provenance: ProcessingProvenance;
+}
+```
+
+## HdrTransfer
+
+The only output transfer in 2.0: unclipped float32 linear values (PQ and HLG are not shipped).
+
+```ts
+export type HdrTransfer = "linear-float32";
+```