@photivra/engine 1.5.0 → 2.1.0

package/docs/api/output-print-detail.md

@@ -1,11 +1,11 @@
 # output/print-detail.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.
 
 ## calculatePrintRegionDetail
 
-Calculate one coherent regional fundamental and its print reference scale.
-Acquisition remains unknown; no MTF, noise, compression or perceptual pass is produced.
+Calculates the strength of one grating frequency in a region and its print reference scale.
+How the image was acquired stays unknown. No MTF, noise, compression or perceptual pass is reported.
 
 ```ts
 export function calculatePrintRegionDetail(value: PrintRegionDetailInput): CalculationResult<PrintRegionDetailAssessment>;
@@ -15,7 +15,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## MAX_PRINT_DETAIL_REGION_SAMPLES
 
-Work bound for one dense ROI, not an actual-device capability claim.
+Work limit for one dense region of interest (ROI). It does not say what a real device can handle.
 
 ```ts
 MAX_PRINT_DETAIL_REGION_SAMPLES = 65536
@@ -23,8 +23,8 @@ MAX_PRINT_DETAIL_REGION_SAMPLES = 65536
 
 ## parsePrintRegionDetailInput
 
-Parse/copy bounded, untrusted region/source/target data and existing Print geometry.
-Unknowns, sparse arrays and factual-reference-only numeric samples fail closed.
+Parses and copies untrusted, bounded region, source and target data and the existing print geometry.
+Unknown fields, sparse arrays and samples marked factual-reference-only are rejected.
 
 ```ts
 export function parsePrintRegionDetailInput(value: unknown): PrintRegionDetailInput;
@@ -34,7 +34,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PRINT_REGION_DETAIL_MODEL_VERSION
 
-Metric/protocol identity; independent of the root creator version.
+Version of this metric and protocol. Independent of the engine version.
 
 ```ts
 PRINT_REGION_DETAIL_MODEL_VERSION = "0.1.0" as const
@@ -42,8 +42,8 @@ PRINT_REGION_DETAIL_MODEL_VERSION = "0.1.0" as const
 
 ## PrintDetailRegion
 
-Selected half-open rectangle in the represented oriented retained raster.
-Depth is descriptive, in metres; null explicitly means unknown.
+The selected half-open rectangle in the oriented, retained source image.
+Depth is descriptive, in metres; null means unknown.
 
 ```ts
 export interface PrintDetailRegion {
@@ -57,7 +57,7 @@ export interface PrintDetailRegion {
 
 ## PrintDetailSource
 
-Exact represented source; content hash and decoding are caller assertions.
+The exact source image. The caller asserts the content hash and decoding; the engine does not check them.
 
 ```ts
 export interface PrintDetailSource {
@@ -76,7 +76,7 @@ export interface PrintDetailSource {
 
 ## PrintRegionDetailAssessment
 
-Immutable snapshot with no full-system, artifact, perception or print-quality pass.
+Frozen result. It never reports a pass for the full system, artefacts, perception or print quality.
 
 ```ts
 export interface PrintRegionDetailAssessment {
@@ -104,7 +104,7 @@ export interface PrintRegionDetailAssessment {
 
 ## PrintRegionDetailInput
 
-Own/reusable scalar relative-linear ROI samples; no RGB/luma conversion is inferred.
+Input: single-channel, relative-linear ROI samples that are the caller's own or reusable data. No RGB or luma conversion is assumed.
 
 ```ts
 export interface PrintRegionDetailInput {
@@ -119,7 +119,7 @@ export interface PrintRegionDetailInput {
 
 ## PrintSinusoidalMeasurement
 
-Calculated coefficients for one declared grating; residual is not a noise metric.
+Fitted coefficients for one declared grating. The residual is not a noise measurement.
 
 ```ts
 export interface PrintSinusoidalMeasurement {
@@ -133,7 +133,7 @@ export interface PrintSinusoidalMeasurement {
 
 ## PrintSinusoidalTarget
 
-Coherent integer Fourier mode; x right/y down, arbitrary phase at first ROI sample.
+The target grating: a whole-number Fourier mode across the ROI (x right, y down), with any phase at the first ROI sample.
 Input modulation is dimensionless, positive and at most one.
 
 ```ts

package/docs/api/output-print-jpeg.md

@@ -1,10 +1,10 @@
 # output/print-jpeg.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.
 
 ## createPrintJpegTask
 
-Filtering uses exact source-pixel area overlap after decoding the explicitly declared 8-bit SDR stage.
+Creates the export task. Filtering weights each source pixel by its exact area overlap, after decoding the declared 8-bit SDR source.
 
 ```ts
 export function createPrintJpegTask(input:PrintJpegInput,provider:PrintJpegProvider):PrintJpegTask;
@@ -14,7 +14,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePrintJpegInput
 
-Admission-only; source detail/perception/printer qualification are separate contracts.
+Validates the input only. Source detail, perception and printer suitability are checked by separate APIs.
 
 ```ts
 export function parsePrintJpegInput(input:PrintJpegInput):PrintJpegInput;
@@ -27,7 +27,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-PRINT_JPEG_SCHEMA_VERSION="0.1.0" as const
+PRINT_JPEG_SCHEMA_VERSION="0.2.0" as const
 ```
 
 ## PrintJpegInput
@@ -37,12 +37,26 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface PrintJpegInput {
   source:PrintJpegSource;
-  /** Integer crop in the declared oriented output source, not crop-local sensor/CFA coordinates. */
+  /** Integer crop in the oriented output source image, not in sensor or CFA (colour filter array) coordinates. */
   crop:RasterRect;
   outputWidth:number;outputHeight:number;
   quantizationStep:number;
   maximumEncodedBytes:number;
+  /**
+   * Maximum provider `readTile` calls. The task reads each crop pixel exactly once, in tiles of at most
+   * 256 x 32 pixels aligned to the crop origin, so it needs ceil(crop.height/32) x ceil(crop.width/256)
+   * reads; a smaller budget fails before the first read.
+   */
   maximumProviderReads:number;
+  /**
+   * Optional physical print density in pixels per inch (1..65535) from the caller's print plan. When present,
+   * EXIF IFD0 records XResolution = YResolution = this value as a RATIONAL with ResolutionUnit = 2 (inches),
+   * and JFIF APP0 records units = 1 with the nearest integer density (JFIF density fields are uint16).
+   * When omitted no physical size is claimed: JFIF keeps units = 0 with a 1:1 aspect ratio. Exif 2.32 makes
+   * the IFD0 resolution tags mandatory and says an unknown resolution "shall" be recorded as 72 dpi, so IFD0
+   * carries 72/1 with ResolutionUnit = 2; that is the standard's unknown-resolution marker, not a print size.
+   */
+  pixelsPerInch?:number;
 }
 ```
 
@@ -62,7 +76,10 @@ export interface PrintJpegOutput {
   sourceStage:"post-SDR-8-bit-quantization";
   digitalUpscalingApplied:false;
   sourceBytesVerified:false;
+  /** Provider calls made: ceil(crop.height/32) x ceil(crop.width/256) tiles, each crop pixel read once. */
   providerReads:number;
+  /** Byte behaviour of the baseline encoder that produced `bytes`. */
+  encoderId:typeof EXPORT_JPEG_ENCODER_ID;
 }
 ```
 

package/docs/api/output-print-plan.md

@@ -1,12 +1,12 @@
 # output/print-plan.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.
 
 ## calculatePrintPlan
 
-Resolve the minimum exact-native-ratio file under declared sampling/lab constraints.
-Angular guidance is approximate as a usage criterion; geometry is calculated.
-No source detail, perceived quality, serializer or resource availability is assessed.
+Finds the smallest file, at the exact native aspect ratio, that meets the declared sampling and lab constraints.
+The angular guidance is an approximate rule of thumb; the geometry itself is calculated exactly.
+It does not assess source detail, perceived quality, file writing or available resources.
 
 ```ts
 export function calculatePrintPlan(value: PrintPlanInput): CalculationResult<PrintPlan>;
@@ -16,8 +16,8 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculatePrintSizeLimit
 
-Calculate a conditional size bound. Lab constraints require individual plans;
-this first size-query contract reports them as unsupported rather than ignoring them.
+Calculates the largest print size under the stated conditions. Lab constraints need individual plans,
+so this size query reports them as unsupported rather than ignoring them.
 
 ```ts
 export function calculatePrintSizeLimit(value: PrintSizeLimitInput): CalculationResult<PrintSizeLimit>;
@@ -27,7 +27,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePrintPlanInput
 
-Validate and copy an untrusted Print request; never infer native authority.
+Validates and copies an untrusted print request. It never assumes the source is native if that is not declared.
 
 ```ts
 export function parsePrintPlanInput(value: unknown): PrintPlanInput;
@@ -37,7 +37,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PrintedImageSize
 
-Flat printed image area; excludes paper, borders and wraps.
+The flat printed image area. It excludes paper margins, borders and canvas wraps.
 
 ```ts
 export interface PrintedImageSize { width: number; height: number; unit: PrintLength["unit"] }
@@ -45,7 +45,7 @@ export interface PrintedImageSize { width: number; height: number; unit: PrintLe
 
 ## PrintLength
 
-Physical length, separate from raster pixels and printer dots.
+A physical length. Not to be confused with image pixels or printer dots.
 
 ```ts
 export interface PrintLength { value: number; unit: "mm" | "cm" | "inches" | "m" }
@@ -53,7 +53,7 @@ export interface PrintLength { value: number; unit: "mm" | "cm" | "inches" | "m"
 
 ## PrintNativeSource
 
-Declared authoritative geometry, not a preview or resampled pixel count.
+The declared native source geometry. Not a preview or a resampled pixel count.
 
 ```ts
 export type PrintNativeSource =
@@ -63,7 +63,7 @@ export type PrintNativeSource =
 
 ## PrintPlan
 
-Finite conditional plan. Null recommendation never authorizes an upscale.
+A plan, valid only under its stated conditions. A null recommendation never means it is fine to upscale.
 
 ```ts
 export interface PrintPlan {
@@ -88,7 +88,7 @@ export interface PrintPlan {
 
 ## PrintPlanInput
 
-Exact-ratio output policy. Physical aspect tolerance is explicit and reported.
+Plan input. The output keeps the exact native aspect ratio; the allowed physical aspect error is explicit and reported.
 
 ```ts
 export interface PrintPlanInput {
@@ -103,7 +103,7 @@ export interface PrintPlanInput {
 
 ## PrintProviderConstraints
 
-Caller-supplied lab constraints; no vendor catalog or delivery guarantee.
+Print lab requirements supplied by the caller. There is no vendor catalogue and no guarantee of what a lab will accept.
 
 ```ts
 export interface PrintProviderConstraints {
@@ -116,7 +116,7 @@ export interface PrintProviderConstraints {
 
 ## PrintRasterSampling
 
-Per-axis density and angular pitch; angular values are geometry, not acuity.
+Pixel density and angular pixel pitch for each axis. The angles are pure geometry, not a measure of visual acuity.
 
 ```ts
 export interface PrintRasterSampling {
@@ -128,7 +128,7 @@ export interface PrintRasterSampling {
 
 ## PrintSamplingCriterion
 
-Explicit angular convention; manual PPI starts a different plan.
+How to choose pixel density: one of three angular criteria at the viewing distance, or a manual PPI (pixels per inch), which gives a different kind of plan.
 
 ```ts
 export type PrintSamplingCriterion =
@@ -140,7 +140,7 @@ export type PrintSamplingCriterion =
 
 ## PrintSizeLimit
 
-Semantic bounds avoid Infinity sentinels; no-positive-size differs from invalid input.
+Result of the size query. A status says "unbounded" rather than using Infinity. "no-positive-size" is a valid answer, not an input error.
 
 ```ts
 export interface PrintSizeLimit {
@@ -154,8 +154,8 @@ export interface PrintSizeLimit {
 
 ## PrintSizeLimitInput
 
-Size-limit query retains the reference image aspect and criterion.
-Proportional viewing scales the supplied reference distance with both image axes.
+Input for the largest-print-size query. It keeps the reference plan's aspect ratio and criterion.
+With proportional viewing, the reference viewing distance scales with the image size.
 
 ```ts
 export interface PrintSizeLimitInput {

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(