@photivra/engine 2.8.1 → 2.10.0

package/docs/USAGE.md

@@ -7516,6 +7516,36 @@ const view = await simulateDisplayView({ scene: { preset: "slanted-edge" }, sens
 console.log(view.kind, view.view.scaleX, view.assumptions.find((a) => a.id === "view.definition")?.value);
 ```
 
+#### Sharing AHD correction states between workers
+
+With `output.demosaic: "ahd"`, low-signal display pixels read correction states that each realm (a page, a Web Worker)
+computes and keeps for itself. Two workers can split a part's states and exchange them instead of both computing all
+of them; the renders have the same bytes either way (see "AHD at low signal" in
+[DISPLAY_VIEW.md](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#ahd-at-low-signal)). Import only
+states whose key a prepared view reported. The two handles below run in one script for the example; in an app each
+runs in its own worker, and the arrays travel with `postMessage(set, [set.gridKeys.buffer, set.values.buffer])`.
+
+```ts
+import { serializeDisplayViewCorrectionStates, bindDisplayViewCorrectionStates, prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
+
+const request: SimulateCaptureOptions = { scene: { preset: "uniform", reflectance: 0.18 }, exposure: { iso: 1600, shutterSeconds: 1 / 2000 },
+  sensor: { pixelPitchMicrometers: 1.4 }, output: { width: 200, height: 150, demosaic: "ahd" } };
+const part = { width: 20, height: 15, region: { x: 0, y: 0, width: 10, height: 8 } };
+// Each worker prepares the same request; the key says which states it reads.
+const workerA = await prepareDisplayView(request), workerB = await prepareDisplayView(request);
+console.log(workerA.correctionKey() === workerB.correctionKey());
+// Worker A finds the states the part needs (no image, no state computed) and gives half to each worker.
+const { gridKeys } = await workerA.collectCorrectionStates(part);
+const half = Math.ceil(gridKeys.length / 2);
+const fromA = await workerA.computeCorrectionStates(gridKeys.slice(0, half));
+const fromB = await workerB.computeCorrectionStates(gridKeys.slice(half));
+// Each worker imports the other's share (in one realm, as here, the second import adds nothing new).
+console.log(bindDisplayViewCorrectionStates([fromB]), bindDisplayViewCorrectionStates([fromA]));
+// Either worker now renders the part without computing a state; a new worker can start from an export.
+const view = await workerA.render(part);
+console.log(view.diagnostics.ahdCorrectedPixelCount, serializeDisplayViewCorrectionStates().map((set) => set.gridKeys.length));
+```
+
 ### Facade 2.0 options: output, demosaic, optics and motion
 
 Each 2.0 option is opt-in and uses an existing public contract. Without them, the facade's output is

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

@@ -14,3 +14,13 @@ was exactly a negative half-integer. The repository's test images are unchanged.
 ```ts
 EXPORT_JPEG_ENCODER_ID = "photivra-baseline-jpeg-444-v2" as const
 ```
+
+## JpegStripBits
+
+The entropy-coded bits of consecutive blocks of one image, coded apart from the blocks before them (`encodeJpegStrip`):
+the first block's quantized coefficients (3 × 64, natural order), whose DC differences need the block before; the other
+blocks' bits, unstuffed, most-significant first; and the last block's DC values, which the next strip's first block needs.
+
+```ts
+export interface JpegStripBits { first: Float64Array; bits: Uint8Array; bitLength: number; blockCount: number; lastDc: Float64Array }
+```

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.8.1" as const
+ENGINE_API_VERSION = "2.10.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.8.1",
-  "engineApiVersion": "2.8.1",
+  "packageVersion": "2.10.0",
+  "engineApiVersion": "2.10.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -212,6 +212,11 @@
       "source": "src/processing/denoise.ts",
       "kind": "type"
     },
+    {
+      "name": "bindDisplayViewCorrectionStates",
+      "source": "src/facade/display-view.ts",
+      "kind": "runtime"
+    },
     {
       "name": "bindIsoCapabilityToExposureCapabilities",
       "source": "src/equipment/iso-capabilities.ts",
@@ -2097,6 +2102,11 @@
       "source": "src/capture/native-environment-raw.ts",
       "kind": "runtime"
     },
+    {
+      "name": "composePrintJpegStrips",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "runtime"
+    },
     {
       "name": "composeRelativeErrorBounds",
       "source": "src/gpu/image-kernel-execution.ts",
@@ -2377,6 +2387,11 @@
       "source": "src/color/illuminants.ts",
       "kind": "runtime"
     },
+    {
+      "name": "createPrintJpegStrip",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "runtime"
+    },
     {
       "name": "createPrintJpegTask",
       "source": "src/output/print-jpeg.ts",
@@ -2592,6 +2607,16 @@
       "source": "src/core/spectral-composition.ts",
       "kind": "type"
     },
+    {
+      "name": "DisplayViewCorrectionStateKeys",
+      "source": "src/facade/display-view.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewCorrectionStateSet",
+      "source": "src/facade/display-view.ts",
+      "kind": "type"
+    },
     {
       "name": "DisplayViewResult",
       "source": "src/facade/simulate-capture.ts",
@@ -3882,6 +3907,11 @@
       "source": "src/equipment/iso-capabilities.ts",
       "kind": "type"
     },
+    {
+      "name": "JpegStripBits",
+      "source": "src/capture/export-jpeg.ts",
+      "kind": "type"
+    },
     {
       "name": "LateralCaLensCorrection",
       "source": "src/output/lens-corrections.ts",
@@ -5522,6 +5552,16 @@
       "source": "src/output/print-jpeg.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintJpegStrip",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "type"
+    },
+    {
+      "name": "PrintJpegStripInput",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintJpegTask",
       "source": "src/output/print-jpeg.ts",
@@ -7842,6 +7882,11 @@
       "source": "src/sensor/dark-current.ts",
       "kind": "type"
     },
+    {
+      "name": "serializeDisplayViewCorrectionStates",
+      "source": "src/facade/display-view.ts",
+      "kind": "runtime"
+    },
     {
       "name": "serializeNativeRawDng",
       "source": "src/capture/native-raw-dng.ts",
@@ -7867,6 +7912,11 @@
       "source": "src/capture/simulated-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "serializeSimulatedCaptureDngFromParts",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "setExposureCompensationOnMeterTarget",
       "source": "src/exposure/metering-target.ts",
@@ -7942,6 +7992,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SIMULATE_CAPTURE_FAST_OPTIONS",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS",
       "source": "src/facade/simulate-capture.ts",
@@ -7977,11 +8032,31 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureDemosaicRecord",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureDngPart",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureExposureMode",
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureFastOption",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureFastReport",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureLensDistortion",
       "source": "src/facade/simulate-capture.ts",

package/docs/api/facade-display-view.md

@@ -0,0 +1,50 @@
+# facade/display-view.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.
+
+## bindDisplayViewCorrectionStates
+
+2.10 (#447): adds states another realm computed (an export, or `computeCorrectionStates` results) to this realm's cache and
+returns the number of states added. For each entry, the grid keys its setup does not hold yet are appended; known ones are
+left as they are (a state's values follow from its key, so they are equal). Every entry is checked before the cache is
+touched: `key` a non-empty string, `gridKeys` an Int32Array of grid keys, `values` a Float64Array of 3 × `gridKeys.length`
+finite numbers; otherwise it fails with an InvalidConfigurationError and the cache is unchanged. The cache's bounds apply as
+in a render: an unknown key creates a setup and can evict the least recently used of the four kept, and a setup that
+reaches 65 536 states is cleared before the next one is added. Import only keys a prepared view reported
+(`correctionKey()`), so states a render here will read.
+
+```ts
+export function bindDisplayViewCorrectionStates(entries: readonly DisplayViewCorrectionStateSet[]): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DisplayViewCorrectionStateKeys
+
+2.10 (#447): the grid keys of the states a region needs (`PreparedDisplayView.collectCorrectionStates`), ascending.
+
+```ts
+export interface DisplayViewCorrectionStateKeys { key: string; gridKeys: Int32Array }
+```
+
+## DisplayViewCorrectionStateSet
+
+2.10 (#447): the AHD low-signal correction states of one setup, as a realm sends them to another. `key` is the setup's
+correction key (`PreparedDisplayView.correctionKey()`), `gridKeys[i]` a state's grid key and `values[3·i …]` its three
+values (28 bytes per state). Both arrays are transferable.
+
+```ts
+export interface DisplayViewCorrectionStateSet { key: string; gridKeys: Int32Array; values: Float64Array }
+```
+
+## serializeDisplayViewCorrectionStates
+
+2.10 (#447): the AHD low-signal correction states this JavaScript realm holds (a Web Worker, a page), one entry per cached
+setup, least recently used first, each state's grid key and three values copied out. Another realm adds them with
+{@link bindDisplayViewCorrectionStates}; a render there then reads them instead of computing them, with the same bytes.
+
+```ts
+export function serializeDisplayViewCorrectionStates(): DisplayViewCorrectionStateSet[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/facade-scene-radiance.md

@@ -175,7 +175,8 @@ export type SceneMaterialPoint = Omit<ScenePlanePoint, "wavelengthNanometers">;
 
 ## ScenePlanePoint
 
-A point of the scene plane passed to caller scene functions.
+A point of the scene plane passed to caller scene functions: a new object for every call, which the engine does not read
+after the call (not frozen: freezing cost about 40 % of a chart lookup).
 
 ```ts
 export interface ScenePlanePoint {

package/docs/api/facade-simulate-capture.md

@@ -30,7 +30,9 @@ export interface DisplayViewResult {
    * milliseconds (diagnostic only; never affects the samples).
    */
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
-    timingsMs: { view: number; total: number } };
+    timingsMs: { view: number; total: number };
+    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
+    fast: SimulateCaptureFastReport };
   provenance: { scientificStatus: "approximation"; cameraPresetId: string; cameraPresetVersion: string; evidence: readonly EvidenceProvenance[];
     composedContracts: readonly string[]; limitations: readonly string[] };
   /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
@@ -62,6 +64,23 @@ export interface IdealReferenceResult {
 }
 ```
 
+## serializeSimulatedCaptureDngFromParts
+
+Writes the whole-frame DNG of `options` (`output.format: "dng"`, no `output.region`) from the packed RAW of region renders of
+the same request (#391), so the RAW can render in parallel. A region render's native sites are the same sites as the whole
+render's (each site's seeds come from its index in the whole raster), so the joined RAW is the whole render's RAW, and the
+request is resolved and written exactly as `simulateCapture` writes its DNG: the bytes are the same. The parts must cover
+every native site of the frame; where they overlap (each region carries the demosaic margin) their sites must agree. Region
+renders of the request with any format serve (a region's own `output.format` does not change its RAW). A region cannot take
+`output.whiteBalance: "auto"` or `output.dng`: render the parts with a fixed white balance (the RAW codes do not depend on the
+white-balance intent) and pass the DNG's own options here, where auto white balance is measured over the joined frame.
+
+```ts
+export async function serializeSimulatedCaptureDngFromParts(options: SimulateCaptureOptions, parts: readonly SimulateCaptureDngPart[]): Promise<NativeRawDng>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
 ## SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES
 
 Default midpoint samples per axis of `sensor.pixelAperture: "box"`.
@@ -101,6 +120,16 @@ Version of how the facade builds requests. It changes whenever the same input wo
 SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
 ```
 
+## SIMULATE_CAPTURE_FAST_OPTIONS
+
+The options that take the exact-or-fast flag (#395), in the path style of {@link SIMULATE_CAPTURE_COST_OPTIONS}: each accepts
+the record form with `fast` and is reported in `diagnostics.fast.applied` when it runs. Every one of them takes the flag,
+whether or not it has a fast method yet; one without runs exact and reports `false`.
+
+```ts
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+```
+
 ## SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS
 
 Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform.
@@ -176,6 +205,25 @@ edge-directed method that reduces zipper and false colour on sharp edges.
 export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
+## SimulateCaptureDemosaicRecord
+
+`output.demosaic` as a record (#395): the demosaic and its `fast` override (see {@link SimulateCaptureOptions.fast}).
+
+```ts
+export interface SimulateCaptureDemosaicRecord { kind: SimulateCaptureDemosaic; fast?: boolean }
+```
+
+## SimulateCaptureDngPart
+
+One part of a whole-frame DNG (#391): a region render's packed RAW and where its native sites lie (`result.raw`, `result.region`).
+
+```ts
+export interface SimulateCaptureDngPart {
+  raw: Pick<NativeRawOutput, "codes" | "blackLevels" | "digitalSaturationCodes" | "saturationFlags" | "effectiveSaturationCodes">;
+  region: { nativeRect: { x: number; y: number; width: number; height: number } };
+}
+```
+
 ## SimulateCaptureExposureMode
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -184,6 +232,29 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
 ```
 
+## SimulateCaptureFastOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[number];
+```
+
+## SimulateCaptureFastReport
+
+`diagnostics.fast` of a capture or display view (#395): what was asked for and what ran.
+
+```ts
+export interface SimulateCaptureFastReport {
+  /** True when `fast: true` was given at the top level or in any option's record. */
+  requested: boolean;
+  /** Each fast-capable option that ran, in {@link SIMULATE_CAPTURE_FAST_OPTIONS} order: true where its fast method ran. */
+  applied: Readonly<Partial<Record<SimulateCaptureFastOption, boolean>>>;
+  /** `engine-reference` when every option ran exact; `approximation-with-a-priori-bound` when any fast method ran (the WebGPU execution record's values). */
+  assurance: "engine-reference" | "approximation-with-a-priori-bound";
+}
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -304,8 +375,8 @@ export interface SimulateCaptureOptions {
      * through `prepareRgbGamutMapping`: constant CIELAB L* and hue, chroma above 90 % of the boundary compressed.
      */
     gamutMapping?: "clip" | "perceptual";
-    /** Default: the 1.0 facade's bilinear RGGB kernels. */
-    demosaic?: SimulateCaptureDemosaic;
+    /** Default: the 1.0 facade's bilinear RGGB kernels. The record form (#395) adds a `fast` override. */
+    demosaic?: SimulateCaptureDemosaic | SimulateCaptureDemosaicRecord;
     /** Default "margin". */
     borderHandling?: SimulateCaptureBorderHandling;
     /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
@@ -363,6 +434,13 @@ export interface SimulateCaptureOptions {
      */
     pixelAperture?: SimulateCapturePixelAperture;
   };
+  /**
+   * Exact or fast (#395). `false` or omitted: every option runs its exact method, the engine reference. `true`: each option
+   * listed in {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of
+   * the exact one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option
+   * only. `diagnostics.fast` reports what was requested and what ran. No option has a fast method yet, so every result is exact.
+   */
+  fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
   /** Called after each committed RAW, development or JPEG tile. Cannot change output. */
@@ -380,10 +458,10 @@ export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png"
 
 ## SimulateCapturePixelAperture
 
-Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule.
+Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule; `fast` (#395) overrides the top-level flag.
 
 ```ts
-export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number };
+export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number; fast?: boolean };
 ```
 
 ## SimulateCaptureProgress
@@ -504,6 +582,8 @@ export interface SimulateCaptureResult {
      * the user's device.
      */
     options: readonly SimulateCaptureCostOption[];
+    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
+    fast: SimulateCaptureFastReport;
   };
   provenance: {
     scientificStatus: "approximation";
@@ -531,9 +611,9 @@ frequency 1/(2·pitch)).
 
 ```ts
 export type SimulateCaptureSensorAntiAliasing =
-  | { kind: "four-spot"; separationSites?: number }
-  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
-  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+  | { kind: "four-spot"; separationSites?: number; fast?: boolean }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number; fast?: boolean }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[]; fast?: boolean };
 ```
 
 ## SimulateCaptureWhiteBalance

package/docs/api/facade-simulate-display-view.md

@@ -11,8 +11,30 @@ setup: use it to render one view in many regions, for example on each worker of
 
 ```ts
 export interface PreparedDisplayView {
-  /** Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. */
+  /**
+   * Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup and the
+   * realm's AHD correction states, which never change a byte (docs/DISPLAY_VIEW.md, "AHD at low signal").
+   */
   render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+  /**
+   * 2.10 (#447): the key of this request's AHD low-signal correction states, or null when the request has no AHD
+   * (`output.demosaic` other than "ahd"). Every input of the key is fixed when the request is prepared; two prepared views
+   * with the same key read the same states.
+   */
+  correctionKey(): string | null;
+  /**
+   * 2.10 (#447): the grid keys of every correction state a render of `view` reads (ascending, whether or not this realm holds
+   * them), found by a render of the view's region that records the states instead of computing them. No image is returned;
+   * it costs about one render whose states are all held. Fails with an InvalidConfigurationError when the request has no AHD.
+   */
+  collectCorrectionStates(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateKeys>;
+  /**
+   * 2.10 (#447): computes the correction states of `gridKeys` (from `collectCorrectionStates`, or a share of them) as a render
+   * would, stores them in this realm's cache and returns their values, for {@link bindDisplayViewCorrectionStates} in
+   * another realm. States this realm holds are read, not computed. Yields and honours `signal` like `render`. Fails with an
+   * InvalidConfigurationError when the request has no AHD or a grid key is out of range.
+   */
+  computeCorrectionStates(gridKeys: Int32Array, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateSet>;
 }
 ```
 

package/docs/api/gpu-image-kernel-execution.md

@@ -51,6 +51,11 @@ export interface ImageKernelExecution {
   fallbackReason: ImageKernelFallbackReason | null;
   arithmetic: "float64" | "float32";
   assurance: "engine-reference" | "approximation-with-a-priori-bound";
+  /**
+   * The exact-or-fast flag in the facade's words (#395): false for `cpu-reference` (the engine reference), true for
+   * `webgpu-f32` (a bounded approximation). `backend` still names where the work ran.
+   */
+  fast: boolean;
   /**
    * True only for `cpu-reference`. Bit-exact identities (SHA-256 artifact bindings, byte-parity fixtures,
    * cross-engine determinism hashes) are CPU-only and must never be computed from a `webgpu-f32` result.

package/docs/api/optics-diffraction-psf-profile.md

@@ -72,7 +72,7 @@ export interface DiffractionLimitedPsfProfile {
   /** Largest truncated energy over the wavelengths. */
   maximumTruncatedEnergyFraction: number;
   /**
-   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ 192 (cells far larger than the pattern) use the real-space
+   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ `AIRY_REAL_SPACE_MINIMUM_BETA` (192 in 2.5–2.8.1, then 32) use the real-space
    * encircled-energy method; `realSpaceWavelengthsNm` lists them, and `method` is `"frequency-domain-and-real-space"` when both ran.
    * `maximumRadialNodes` counts frequency-domain radial nodes (0 when only the real-space method ran); `maximumAngularNodes` the
    * angular nodes of either method (for the real-space method, all θ nodes of one wavelength).

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

@@ -2,6 +2,31 @@
 
 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.
 
+## composePrintJpegStrips
+
+Joins the strips of a 1:1 Print JPEG (`createPrintJpegStrip`), covering the image top to bottom in order, into its file:
+the same bytes `createPrintJpegTask` writes for the plan and the same source pixels. No source is read, so the output's
+`providerReads` is 0.
+
+```ts
+export function composePrintJpegStrips(input:PrintJpegInput,strips:readonly PrintJpegStrip[]):PrintJpegOutput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createPrintJpegStrip
+
+Codes rows of a 1:1 Print JPEG (output size equal to the crop) apart from the rows before them, so a large file's strips
+can be written on separate workers. `strip.y` is a multiple of 8 and `strip.height` a multiple of 8 unless the strip ends at
+the image's bottom; `strip.samples` are those crop rows' 8-bit sRGB RGB, crop-wide. `composePrintJpegStrips` joins strips that
+cover the image, in order, into the bytes `createPrintJpegTask` writes for the same plan and source pixels.
+
+```ts
+export function createPrintJpegStrip(input:PrintJpegInput,strip:PrintJpegStripInput):PrintJpegStrip;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## createPrintJpegTask
 
 Creates the export task. Filtering weights each source pixel by its exact area overlap, after decoding the declared 8-bit SDR source.
@@ -123,6 +148,22 @@ export interface PrintJpegSource {
 }
 ```
 
+## PrintJpegStrip
+
+A strip of a 1:1 Print JPEG's coded blocks (`createPrintJpegStrip`), for `composePrintJpegStrips`.
+
+```ts
+export interface PrintJpegStrip {readonly y:number;readonly height:number;readonly width:number;readonly quantizationStep:number;readonly bits:JpegStripBits}
+```
+
+## PrintJpegStripInput
+
+Rows of a 1:1 Print JPEG for `createPrintJpegStrip`: crop rows `y` to `y + height` (relative to the crop), crop-wide RGB.
+
+```ts
+export interface PrintJpegStripInput {y:number;height:number;samples:Uint8Array}
+```
+
 ## PrintJpegTask
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",