@photivra/engine 1.4.0 → 2.0.0

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

@@ -1,10 +1,10 @@
 # output/native-capture-sdr.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.4.0**, root API **1.4.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;
 }
 ```

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

@@ -1,11 +1,11 @@
 # output/print-detail.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.4.0**, root API **1.4.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.4.0**, root API **1.4.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 {