@photivra/engine 1.5.0 → 2.1.0

package/docs/api/output-geometric-transforms.md

@@ -1,10 +1,10 @@
 # output/geometric-transforms.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.
 
 ## AffineGeometricTransform
 
-Explicit destination-to-source affine map, including rotation/shear/offset.
+Explicit destination-to-source affine map, which can include rotation, shear and offset.
 
 ```ts
 export interface AffineGeometricTransform extends TransformIdentity {
@@ -14,9 +14,20 @@ export interface AffineGeometricTransform extends TransformIdentity {
 }
 ```
 
+## BrownConradyGeometricTransform
+
+Schema 0.2.0: Brown-Conrady distortion. A correction reads the distorted data at the position mapped from each ideal destination point.
+
+```ts
+export interface BrownConradyGeometricTransform extends TransformIdentity {
+  kind: "brown-conrady";
+  profile: BrownConradyDistortionProfile;
+}
+```
+
 ## calculateComposedGeometricMapping
 
-Authoritative display-to-capture map and full local directional derivatives.
+Maps a display point to the capture, with the full local derivatives in each direction.
 
 ```ts
 export function calculateComposedGeometricMapping(input: {
@@ -28,7 +39,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateForwardGeometricMapping
 
-Capture-to-display bridge for focus, metering and overlays; reverses the same maps.
+Maps a capture point to the display, for focus, metering and overlays. It inverts the same maps.
 
 ```ts
 export function calculateForwardGeometricMapping(input: {
@@ -40,7 +51,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateGeometricResampling
 
-Samples an already-formed scalar image once; null output marks missing source support.
+Resamples an already-formed single-channel image once. A null output sample marks missing source data.
 
 ```ts
 export function calculateGeometricResampling(input: {
@@ -52,12 +63,17 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateGeometricSamplingPlan
 
-Resolves one joint validity/crop/AA plan after composing compatible inverse maps.
+Composes compatible inverse maps, then resolves one shared plan for validity, crop and anti-aliasing (AA).
 
 ```ts
 export function calculateGeometricSamplingPlan(input: {
   mapping: PreparedGeometricMapping; sourceRaster: GeometricRaster; destinationRaster: GeometricRaster;
   resampler: GeometricResampler; physicalProjectionDistanceMm: number;
+  /**
+   * Ideal projection of the captured (source) image, used for the reported angles. Omitted or
+   * "rectilinear" keeps the existing atan(mm / projection distance) angles exactly.
+   */
+  sourceProjectionModel?: LensProjectionModel;
 }): CalculationResult<GeometricSamplingPlan>;
 ```
 
@@ -68,12 +84,16 @@ 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
-export type DigitalGeometricTransform = AffineGeometricTransform | RadialGeometricTransform;
+export type DigitalGeometricTransform =
+  | AffineGeometricTransform
+  | RadialGeometricTransform
+  | BrownConradyGeometricTransform
+  | ProjectionRemapGeometricTransform;
 ```
 
 ## GeometricImageDomain
 
-Domains are barriers: only contiguous equal-domain maps share a resample.
+A domain change separates maps: only adjacent maps in the same domain share one resampling pass.
 
 ```ts
 export type GeometricImageDomain = "raw-channel" | "reconstructed-linear" | "processed-output";
@@ -81,7 +101,7 @@ export type GeometricImageDomain = "raw-channel" | "reconstructed-linear" | "pro
 
 ## GeometricJacobian
 
-Row-major derivative d(source mm)/d(destination mm).
+Jacobian (derivative) d(source mm)/d(destination mm), in row-major order.
 
 ```ts
 export type GeometricJacobian = readonly [number, number, number, number];
@@ -102,9 +122,20 @@ export interface GeometricMappingPoint {
 }
 ```
 
+## GeometricProjectionDeclaration
+
+One ideal projection and its mapping scale (focal length, or mm per radian for equirectangular).
+
+```ts
+export interface GeometricProjectionDeclaration {
+  projectionModel: LensProjectionModel;
+  focalLengthMm: number;
+}
+```
+
 ## GeometricRaster
 
-Regular pixel centers on the optical plane: +X right, +Y up; row order down.
+A regular grid of pixel centres on the optical plane: +X right, +Y up; rows run top to bottom.
 
 ```ts
 export interface GeometricRaster {
@@ -117,7 +148,7 @@ export interface GeometricRaster {
 
 ## GeometricResampler
 
-Resampler identity is independent of mapping. Prefiltering is a caller obligation.
+The resampling filter, chosen independently of the mapping. Any prefiltering (anti-aliasing) is the caller's job.
 
 ```ts
 export interface GeometricResampler {
@@ -139,21 +170,21 @@ export interface GeometricSamplingPlan {
   destinationRaster: GeometricRaster;
   resampler: GeometricResampler;
   points: readonly GeometricMappingPoint[];
-  /** Includes exact center-domain support for the selected filter; no edge extension. */
+  /** True where the selected filter has full source support around the pixel centre. Edges are not extended. */
   validSourceMask: readonly boolean[];
-  /** Largest all-valid axis-aligned pixel rectangle, half-open. Null if empty. */
+  /** Largest axis-aligned rectangle of valid pixels (half-open). Null if there is none. */
   jointCrop: { x: number; y: number; width: number; height: number } | null;
   requiresPrefilter: boolean;
   canResample: boolean;
   physicalCapturedFovDegrees: { horizontal: number; vertical: number };
-  /** Envelope of mapped pixel-center rays retained by the joint crop, not edge FOV. */
+  /** Angular extent of the mapped pixel-centre rays kept by the joint crop. It is not the edge-to-edge FOV. */
   retainedSampleRayEnvelopeDegrees: { minX: number; maxX: number; minY: number; maxY: number } | null;
 }
 ```
 
 ## parseDigitalGeometricTransform
 
-Parses strict transform data, rejecting unknown semantics and noninvertible profiles.
+Strictly parses transform data. Unknown kinds or fields and profiles that cannot be inverted are rejected.
 
 ```ts
 export function parseDigitalGeometricTransform(value: unknown): DigitalGeometricTransform;
@@ -163,11 +194,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PreparedGeometricMapping
 
-Serializable prepared state. Maps are applied in listed destination-to-source order.
+Serializable prepared mapping. Maps are applied in the listed order, from destination towards source.
 
 ```ts
 export interface PreparedGeometricMapping {
-  schemaVersion: "0.1.0";
+  /** 0.1.0 when only affine and radial kinds are used; 0.2.0 when a kind added in 2.0 is present. */
+  schemaVersion: "0.1.0" | "0.2.0";
   frameTimeSeconds: number;
   transforms: readonly DigitalGeometricTransform[];
   semanticKey: string;
@@ -177,7 +209,7 @@ export interface PreparedGeometricMapping {
 
 ## prepareGeometricMapping
 
-Prepares deterministic still/frame geometry; time changes require another preparation.
+Prepares a deterministic mapping for one still or frame. A change in time needs a new preparation.
 
 ```ts
 export function prepareGeometricMapping(input: {
@@ -187,9 +219,23 @@ export function prepareGeometricMapping(input: {
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ProjectionRemapGeometricTransform
+
+Schema 0.2.0: change of projection. Each destination point becomes a scene direction (using
+the destination projection), then a source point (using the source projection). Purpose must
+be "projection".
+
+```ts
+export interface ProjectionRemapGeometricTransform extends TransformIdentity {
+  kind: "projection-remap";
+  destinationProjection: GeometricProjectionDeclaration;
+  sourceProjection: GeometricProjectionDeclaration;
+}
+```
+
 ## RadialGeometricTransform
 
-Correction samples physical distorted data at the mapped ideal destination.
+Radial distortion. A correction reads the physically distorted data at the position mapped from each ideal (undistorted) destination point.
 
 ```ts
 export interface RadialGeometricTransform extends TransformIdentity {

package/docs/api/output-lens-corrections.md

@@ -1,12 +1,12 @@
 # output/lens-corrections.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.
 
 ## calculateLensCorrectedCapture
 
-Executes bounded reconstructed-linear corrections on already sampled RGB channels.
-Compatible common geometry plus channel CA is sampled once per channel.
-A gain between geometry components or incompatible domains requires an external staged consumer.
+Applies bounded corrections to RGB channels that are already sampled and linear.
+Compatible shared geometry and per-channel CA are combined, so each channel is resampled once.
+A gain between geometry components, or incompatible domains, needs a separate staged caller.
 
 ```ts
 export function calculateLensCorrectedCapture(input: {
@@ -18,10 +18,10 @@ export function calculateLensCorrectedCapture(input: {
   application: ResolvedLensCorrectionPlan["application"];
   channels: Readonly<Record<LensCorrectionChannel, readonly (number | null)[]>>;
   samplingPlans: Partial<Record<LensCorrectionChannel, GeometricSamplingPlan>>;
-  /** Intersection across all channel footprints, before crop; no missing colors fabricated. */
+  /** Area valid in every channel, before cropping. Missing colours are never made up. */
   validSourceMask: readonly boolean[];
   jointCrop: GeometricSamplingPlan["jointCrop"];
-  /** Gain-stage clipping events before joint support/crop; repeated stages count separately. */
+  /** Clipping events in gain stages, before the shared valid-area crop. Each stage is counted separately. */
   illuminationClippingEventCount: number;
 }>;
 ```
@@ -30,7 +30,8 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculatePeripheralIlluminationCorrection
 
-Applies scalar post-capture gain and reports pre-clip variance; no photon/SNR history rewrite.
+Applies a gain after capture and reports the variance before clipping. It does not rewrite
+the photon or SNR (signal-to-noise ratio) history of the capture.
 
 ```ts
 export function calculatePeripheralIlluminationCorrection(input: {
@@ -43,7 +44,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## GenericLensCorrectionProfile
 
-Exact generic system binding, with components in authoritative application order.
+A correction profile for one exact lens-and-camera system. Components are listed in the order they are applied.
 
 ```ts
 export interface GenericLensCorrectionProfile {
@@ -58,7 +59,7 @@ export interface GenericLensCorrectionProfile {
 
 ## GeometricLensCorrection
 
-A separately declared correction map may deliberately retain physical distortion.
+A distortion correction map, declared separately. It may deliberately leave some physical distortion in place.
 
 ```ts
 export interface GeometricLensCorrection extends CorrectionComponentIdentity {
@@ -69,7 +70,7 @@ export interface GeometricLensCorrection extends CorrectionComponentIdentity {
 
 ## IlluminationLensCorrection
 
-Post-capture scalar gain; strength 0..1 leaves explicit residual falloff.
+Vignetting correction as a gain applied after capture. A strength below 1 deliberately leaves some falloff. Range 0..1.
 
 ```ts
 export interface IlluminationLensCorrection extends CorrectionComponentIdentity {
@@ -81,7 +82,7 @@ export interface IlluminationLensCorrection extends CorrectionComponentIdentity
 
 ## LateralCaLensCorrection
 
-Channel registration only, not longitudinal CA or color shading.
+Lateral CA: shifts colour channels into register. It does not correct longitudinal CA or colour shading.
 
 ```ts
 export interface LateralCaLensCorrection extends CorrectionComponentIdentity {
@@ -92,7 +93,7 @@ export interface LateralCaLensCorrection extends CorrectionComponentIdentity {
 
 ## LensCorrectionCapture
 
-Immutable capture identity accompanies downstream channels for meaningful On/Off comparisons.
+The fixed capture identity travels with the output channels, so On/Off comparisons use the same capture.
 
 ```ts
 export interface LensCorrectionCapture {
@@ -123,7 +124,7 @@ export type LensCorrectionComponent = GeometricLensCorrection | LateralCaLensCor
 
 ## parseGenericLensCorrectionProfile
 
-Strict parser for generic system corrections; no extrapolation or restoration claim.
+Strictly parses a generic correction profile. It does not extrapolate and makes no claim to restore lost detail.
 
 ```ts
 export function parseGenericLensCorrectionProfile(value: unknown): GenericLensCorrectionProfile;
@@ -142,14 +143,15 @@ export interface ResolvedLensCorrectionPlan {
   selectionKind: "camera-selectable" | "reference-bypass";
   components: readonly { component: LensCorrectionComponent; enabled: boolean;
     reason: "selected" | "default" | "mandatory" | "stabilization-dependency" | "component-dependency" | "reference-bypass" }[];
-  /** RAW-like intent remains metadata only in this first foundation. */
+  /** For now, a RAW-like intent is recorded as metadata only. */
   application: "metadata-only" | "bake-downstream";
 }
 ```
 
 ## resolveLensCorrectionPlan
 
-Resolves independent camera states, explicit dependencies, RAW intent and educational bypass.
+Decides which corrections apply for a camera state. It accounts for per-component settings,
+explicit dependencies between components, RAW intent and the educational "corrections off" bypass.
 
 ```ts
 export function resolveLensCorrectionPlan(input: {

package/docs/api/output-native-capture-sdr.md

@@ -1,10 +1,10 @@
 # output/native-capture-sdr.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.
 
 ## calculateNativeCaptureSdrPlan
 
-Validates/admission-plans without reading external samples or allocating a raster.
+Validates the input and plans the task, including its limits, without reading samples or allocating an image.
 
 ```ts
 export function calculateNativeCaptureSdrPlan(input: NativeCaptureSdrInput): NativeCaptureSdrPlan;
@@ -14,7 +14,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## createNativeCaptureSdrTask
 
-Creates a single-use execution owner. Admission is validated before any buffer/provider work.
+Creates a single-use task. Limits are checked before any buffer is allocated or tile is read.
 
 ```ts
 export function createNativeCaptureSdrTask(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider): NativeCaptureSdrTask;
@@ -41,7 +41,7 @@ NATIVE_CAPTURE_SDR_SCHEMA_VERSION = "0.1.0" as const
 
 ## NativeCaptureSdrInput
 
-Metadata-only external float master. Samples must already be color/WB resolved.
+Input. The capture holds only metadata; float samples are read from external storage. Samples must already have colour and white balance applied.
 
 ```ts
 export interface NativeCaptureSdrInput {
@@ -49,7 +49,7 @@ export interface NativeCaptureSdrInput {
   sourcePlaneId: string;
   outputImageStateId: string;
   profile: SdrRenderingProfile;
-  /** Admission limit for retained integer output, before allocation or provider calls. */
+  /** Limit on the size of the integer output. Checked before anything is allocated or any tile is read. */
   maximumOutputBytes: number;
 }
 ```
@@ -61,7 +61,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface NativeCaptureSdrOutput {
   plan: NativeCaptureSdrPlan;
-  /** Caller-owned packed row-major RGB; 16-bit codes are numeric, not serialized endian bytes. */
+  /** Packed RGB codes in row-major order, owned by the caller. 16-bit codes are numbers, not bytes in a particular byte order. */
   integerSamples: Uint8Array | Uint16Array;
   diagnostics: SdrRenderingResult["diagnostics"];
   outputEncoding: SdrRenderingResult["outputEncoding"];
@@ -81,7 +81,7 @@ export interface NativeCaptureSdrPlan {
   outputImageStateId: string;
   profile: SdrRenderingProfile;
   outputBytes: number;
-  /** Logical array payload bound, not JS heap/GPU/process peak memory or device qualification. */
+  /** Upper bound on the bytes held in working arrays. It is not peak JavaScript heap, GPU or process memory, and does not show that a device can run the task. */
   maximumScratchPayloadBytes: number;
   tileCount: number;
 }
@@ -89,19 +89,24 @@ export interface NativeCaptureSdrPlan {
 
 ## NativeCaptureSdrProvider
 
-One provider call at a time. Caller must release decoding/GPU resources on abort/settlement.
+Supplies tiles, one call at a time. The caller must release decoder and GPU resources when the task aborts or finishes.
 
 ```ts
 export interface NativeCaptureSdrProvider {
   readTile(request: Readonly<NativeCaptureSdrTileRequest>, signal: AbortSignal): Promise<NativeCaptureSdrTile>;
-  /** Must yield to the host event loop, allowing cancellation/input events between tiles. */
+  /** Must yield to the host event loop, so cancellation and input events can run between tiles. */
   yieldControl(signal: AbortSignal): Promise<void>;
+  /**
+   * Optional progress observer, called synchronously after each committed tile. It cannot change
+   * output; an exception it throws fails the task like any other error.
+   */
+  onProgress?(progress: NativeTaskProgress): void;
 }
 ```
 
 ## NativeCaptureSdrTask
 
-Single-use task: no partial output escapes; cancel/dispose prevents late publication.
+A single-use task. No partial output is ever returned, and cancel or dispose stops a late result from being published.
 
 ```ts
 export interface NativeCaptureSdrTask {
@@ -111,7 +116,7 @@ export interface NativeCaptureSdrTask {
   run(): Promise<void>;
   cancel(): void;
   dispose(): void;
-  /** Transfers sole retained buffer ownership once. Dispose cannot revoke a transferred buffer. */
+  /** Hands over the only copy of the output buffer, once. Dispose cannot take back a buffer already handed over. */
   takeOutput(): NativeCaptureSdrOutput;
 }
 ```
@@ -126,7 +131,7 @@ export type NativeCaptureSdrTaskState = "ready" | "running" | "completed" | "can
 
 ## NativeCaptureSdrTile
 
-Returned tile is exclusively handed to this call; do not mutate/reuse it. Padding is not image data.
+A tile returned by the provider. It belongs to this call alone; do not change or reuse it. Row padding is not image data.
 
 ```ts
 export interface NativeCaptureSdrTile extends NativeCaptureSdrTileRequest {
@@ -137,7 +142,7 @@ export interface NativeCaptureSdrTile extends NativeCaptureSdrTileRequest {
 
 ## NativeCaptureSdrTileRequest
 
-Absolute coordinates in the selected plane's declared binding, never crop-local sensor indices.
+Tile request. Coordinates are absolute in the selected plane's declared pixel grid, never relative to a crop.
 
 ```ts
 export interface NativeCaptureSdrTileRequest {
@@ -148,3 +153,11 @@ export interface NativeCaptureSdrTileRequest {
   x: number; y: number; width: number; height: number;
 }
 ```
+
+## NativeTaskProgress
+
+Tile progress of a native task: `completedTileCount` of `totalTileCount` tiles are committed.
+
+```ts
+export interface NativeTaskProgress { readonly completedTileCount: number; readonly totalTileCount: number }
+```

package/docs/api/output-png-encoder.md

@@ -0,0 +1,105 @@
+# output/png-encoder.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.
+
+## PNG_ENCODER_ID
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PNG_ENCODER_ID = "photivra-png-rgb-v1" as const
+```
+
+## PNG_ENCODER_LIMITS
+
+Limits, checked before allocation. 100 MP (megapixels) of 16-bit RGB is about 600 MB of filtered scanlines.
+
+```ts
+PNG_ENCODER_LIMITS = Object.freeze({ maximumDimension: 65535, maximumPixels: 100_000_000, maximumIccProfileBytes: 4_000_000 })
+```
+
+## PngCicpPrimaries
+
+ITU-T H.273 ColourPrimaries: bt709 = 1 (also sRGB), display-p3 = 12 (P3 primaries with D65 white; W3C CSS Color 4, also SMPTE EG 432-1), bt2020 = 9 (BT.2020).
+
+```ts
+export type PngCicpPrimaries = "bt709" | "display-p3" | "bt2020";
+```
+
+## PngCicpTransfer
+
+ITU-T H.273 TransferCharacteristics: bt709 = 1, linear = 8, srgb = 13 (sRGB). PQ (16) and HLG (18) are not offered in 2.0.
+
+```ts
+export type PngCicpTransfer = "bt709" | "linear" | "srgb";
+```
+
+## PngColourEncoding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type PngColourEncoding =
+  | { kind: "srgb"; renderingIntent: "perceptual" | "relative-colorimetric" | "saturation" | "absolute-colorimetric" }
+  | { kind: "icc"; profileName: string; profile: Uint8Array }
+  | { kind: "cicp"; primaries: PngCicpPrimaries; transfer: PngCicpTransfer; fullRange: boolean };
+```
+
+## PngContentLightLevel
+
+Content light level in cd/m² (W3C PNG cLLI; ITU-T H.265 content light level SEI; also CTA-861.3); 0 means unknown.
+
+```ts
+export interface PngContentLightLevel {
+  maximumContentLightLevelCdPerSquareMeter: number;
+  maximumFrameAverageLightLevelCdPerSquareMeter: number;
+}
+```
+
+## PngEncodeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PngEncodeInput {
+  width: number;
+  height: number;
+  bitDepth: 8 | 16;
+  /** Interleaved RGB code values, row-major; Uint8Array for 8-bit, Uint16Array for 16-bit. */
+  samples: Uint8Array | Uint16Array;
+  colourEncoding: PngColourEncoding;
+  masteringDisplay?: PngMasteringDisplay;
+  contentLightLevel?: PngContentLightLevel;
+  /** Default "fixed-huffman". */
+  compression?: "stored" | "fixed-huffman";
+  /** PNG filter type 0..4 for every row, or the specification's minimum-sum-of-absolute-differences heuristic. Default "adaptive". */
+  filter?: "none" | "sub" | "up" | "average" | "paeth" | "adaptive";
+}
+```
+
+## PngMasteringDisplay
+
+Mastering display colour volume (W3C PNG mDCV; ITU-T H.265 Annex D SEI; also SMPTE ST 2086): CIE 1931 xy chromaticities and luminance in cd/m².
+
+```ts
+export interface PngMasteringDisplay {
+  redXy: readonly [number, number];
+  greenXy: readonly [number, number];
+  blueXy: readonly [number, number];
+  whiteXy: readonly [number, number];
+  maximumLuminanceCdPerSquareMeter: number;
+  minimumLuminanceCdPerSquareMeter: number;
+}
+```
+
+## serializePngImage
+
+Encode an RGB still image as PNG (colour type 2, no interlace). Samples are written unchanged; 16-bit
+samples are stored big-endian as PNG requires. Throws `InvalidConfigurationError` for any invalid or
+inconsistent field before allocating the scanline buffer.
+
+```ts
+export function serializePngImage(input: PngEncodeInput): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/output-print-contrast-reference.md

@@ -1,10 +1,10 @@
 # output/print-contrast-reference.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.
 
 ## calculatePrintContrastReference
 
-Estimate the restricted published-model threshold; no individual invisibility claim.
+Estimates the detection threshold from the published model, within its limited range. It does not claim that detail is invisible to any particular person.
 
 ```ts
 export function calculatePrintContrastReference(value: PrintContrastReferenceInput): CalculationResult<PrintContrastReference>;
@@ -14,7 +14,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parsePrintContrastReferenceInput
 
-Strictly parse/copy explicit reference conditions; no defaults infer an observer.
+Strictly parses and copies the explicit reference conditions. No defaults are filled in to imply an observer.
 
 ```ts
 export function parsePrintContrastReferenceInput(value: unknown): PrintContrastReferenceInput;
@@ -32,7 +32,7 @@ PRINT_CONTRAST_REFERENCE_MODEL_VERSION = "0.1.0" as const
 
 ## PRINT_CONTRAST_REFERENCE_UPSTREAM_REVISION
 
-Exact MIT-licensed numerical-model source, not a local calibration identity.
+Identifies the exact MIT-licensed model source. It is not a local calibration.
 
 ```ts
 PRINT_CONTRAST_REFERENCE_UPSTREAM_REVISION = "f4b0b722af83001d7af979281e06ca642d36e4e8" as const
@@ -62,21 +62,21 @@ export interface PrintContrastReference {
 
 ## PrintContrastReferenceInput
 
-Narrow reference stimulus, separate from any measured photographic ROI.
-Positive but out-of-domain quantities return unsupported rather than extrapolation.
+The narrow reference stimulus. It is separate from any measured photographic region of interest (ROI).
+Positive values outside the model's range return "unsupported" instead of being extrapolated.
 
 ```ts
 export interface PrintContrastReferenceInput {
   referenceId: string;
   stimulus: "static-neutral-d65-gabor";
   observer: "published-binocular-natural-pupil-reference";
-  /** Uniform D65 background/carrier mean; not the average of a finite photographic ROI. */
+  /** Mean luminance of the uniform D65 background and grating. Not the average of a photographic ROI. */
   meanLuminanceCdPerSquareMeter: number;
   spatialFrequencyCyclesPerDegree: number;
   gaussianEnvelopeSigmaDegrees: number;
   temporalFrequencyHz: number;
   eccentricityDegrees: number;
-  /** Neutral carrier fractional amplitude before the Gaussian envelope; not arbitrary ROI extrema. */
+  /** Fractional amplitude of the neutral grating before the Gaussian envelope. Not taken from ROI minimum and maximum values. */
   modulationMichelson: number;
 }
 ```