@photivra/engine 2.21.0 → 2.23.0

package/docs/api/capture-dng-profile-maps.md

@@ -0,0 +1,141 @@
+# capture/dng-profile-maps.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.
+
+## applyDngProfileGainTableMap
+
+Applies ProfileGainTableMap(2): at each pixel the weight t = clamp(w·(R, G, B, min, max)·2^BaselineExposure, 0, 1)^γ selects a
+gain by linear interpolation at t·N in the table (index clamped to N − 1, SDK), bilinear between map points at the pixel centre's
+relative position (held at the map's edges); R, G and B are multiplied by it.
+
+```ts
+export function applyDngProfileGainTableMap(input: ApplyDngProfileGainTableMapInput): void;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngProfileGainTableMapInput
+
+Options of {@link applyDngProfileGainTableMap}.
+
+```ts
+export interface ApplyDngProfileGainTableMapInput {
+  /** Linear ProPhoto (RIMM, D50) RGB, white-balanced, 1 = clipping white; changed in place. */
+  image: DngRgbImage;
+  map: DngProfileGainTableMap;
+  /** BaselineExposure (stops) not yet applied to `image`: the weight is scaled by 2^stops, as the SDK does. Default 0. */
+  baselineExposureStops?: number;
+  /** Where `image` sits in the stage-3 (ActiveArea) image the map spans. Default: `image` is the whole stage-3 image. */
+  region?: { x: number; y: number; stageWidth: number; stageHeight: number };
+  /** Keep values above 1 (true) or clip to 0..1 (false, the SDR default). */
+  overrange?: boolean;
+}
+```
+
+## applyDngRgbTables
+
+Applies RGBTables: each table maps ProPhoto RGB into its own primaries (clipped to 0..1, the clipped-off part kept and added back
+when GamutExtension is "extend"), encodes it with the table's gamma, interpolates tetrahedrally in the 3D table, decodes and maps
+back (SDK `RefRGBtoRGBTable3D`). The background table (empty name) applies to the whole image. Weighted sum: each masked table's
+result weighted by its mask, the background (the background table's result, or the input) by 1 − min(1, Σ masks), normalized.
+Sequential: each table in file order, blended into the running image by its mask (the background table by 1 − min(1, Σ other masks)).
+A table whose mask is not supplied is skipped (as the SDK skips a name with no SemanticMask); the returned notes say so.
+
+```ts
+export function applyDngRgbTables(input: ApplyDngRgbTablesInput): string[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngRgbTablesInput
+
+Options of {@link applyDngRgbTables}.
+
+```ts
+export interface ApplyDngRgbTablesInput {
+  /** ProPhoto-primaries RGB after the tone curve, 0..1; changed in place. */
+  image: DngRgbImage;
+  tables: DngRgbTables;
+  /** Semantic masks by name (values 0..1, any size; stretched over the image with bilinear interpolation). */
+  masks?: readonly { name: string; width: number; height: number; data: Float32Array }[];
+}
+```
+
+## DngProfileGainTableMap
+
+A parsed ProfileGainTableMap(2): N gains at each of V × H map points, decoded to 32-bit floats.
+
+```ts
+export interface DngProfileGainTableMap {
+  /** 1 for ProfileGainTableMap (52525), 2 for ProfileGainTableMap2 (52544). */
+  version: 1 | 2;
+  pointsV: number; pointsH: number; spacingV: number; spacingH: number; originV: number; originH: number;
+  /** MapPointsN: the table length at each map point. */
+  tablePoints: number;
+  /** MapInputWeights for red, green, blue, min(R,G,B) and max(R,G,B). */
+  inputWeights: [number, number, number, number, number];
+  /** PGTM2: the weight's gamma (1 for version 1). */
+  gamma: number;
+  /** Gains, row-major (v, h, table point). */
+  gains: Float32Array;
+}
+```
+
+## DngRgbImage
+
+An RGB image, interleaved (row, column, channel).
+
+```ts
+export interface DngRgbImage { width: number; height: number; data: Float32Array }
+```
+
+## DngRgbTable
+
+One table of RGBTables: a 3D table of `divisions`³ RGB samples (16-bit, 65535 = 1).
+
+```ts
+export interface DngRgbTable {
+  /** TableSemanticName: the semantic mask it applies within; "" for the background table (the whole image). */
+  semanticName: string;
+  divisions: number;
+  gamma: "linear" | "srgb" | "1.8" | "2.2" | "rec2020";
+  primaries: "srgb" | "adobe-rgb" | "display-p3" | "rec2020" | "prophoto";
+  gamut: "clip" | "extend";
+  /** RGB per node, red slowest then green then blue, length divisions³ × 3. */
+  samples: Uint16Array;
+}
+```
+
+## DngRgbTables
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngRgbTables { compositeMethod: "weighted-sum" | "sequential"; tables: DngRgbTable[] }
+```
+
+## parseDngProfileGainTableMap
+
+Parses ProfileGainTableMap (version 1) or ProfileGainTableMap2 (version 2). Layout: MapPointsV, MapPointsH (LONG), MapSpacingV,
+MapSpacingH, MapOriginV, MapOriginH (DOUBLE), MapPointsN (LONG), MapInputWeights (5 FLOAT); version 2 adds DataType (LONG: 0 uint8,
+1 uint16, 2 float16, 3 float32), Gamma, GainMin, GainMax (FLOAT); then the gains. Integer gains are GainMin + (x/max)·(GainMax −
+GainMin). A single map point on an axis has spacing 1 and origin 0 (SDK).
+
+```ts
+export function parseDngProfileGainTableMap(bytes: Uint8Array, littleEndian: boolean, version: 1 | 2): DngProfileGainTableMap;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseDngRgbTables
+
+Parses RGBTables (52543): table count (LONG, at most 20; 0 means none), CompositeMethod (LONG: 0 weighted sum, 1 sequential), then
+per table LengthTableSemanticName (SHORT), the name's bytes, Divisions, PixelType (0 uint8, 1 uint16, 2 float32), GammaEncoding
+(0 linear, 1 sRGB, 2 γ 1.8, 3 γ 2.2, 4 Rec. 2020), ColorPrimaries (0 sRGB, 1 Adobe RGB, 2 P3, 3 Rec. 2020, 4 ProPhoto) and
+GamutExtension (0 clip, 1 extend), each a BYTE, then Divisions³ RGB samples (uint8 scaled by 256, float scaled by 65535).
+
+```ts
+export function parseDngRgbTables(bytes: Uint8Array, littleEndian: boolean): DngRgbTables | null;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-dng-stage-image.md

@@ -0,0 +1,43 @@
+# capture/dng-stage-image.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.
+
+## developDngStageImage
+
+Builds the stage-2 (CFA) or stage-3 (LinearRaw) image of an imported DNG, normalized 0..1, interleaved by sample.
+
+```ts
+export function developDngStageImage(raw: ImportedDngRaw, options: DevelopDngStageImageOptions = {}): DngStageImageResult;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DevelopDngStageImageOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DevelopDngStageImageOptions {
+  /** The output the development is for ("srgb-8" or "srgb-16" on screen; "dng", "jpeg" or "png" exports). Default "srgb-8" (fast; owner, 2026-11-11). */
+  format?: "srgb-8" | "srgb-16" | "dng" | "jpeg" | "png";
+  /** The speed-versus-accuracy choice (WarpRectilinear resampling); default from `format` (fast on screen, full for exports). */
+  fast?: boolean;
+  /** Apply the opcode lists (default true). */
+  opcodes?: boolean;
+}
+```
+
+## DngStageImageResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngStageImageResult extends DngStageImage {
+  /** 3 for LinearRaw (every opcode list applied), 2 for a CFA mosaic (OpcodeList3 left to the caller). */
+  stage: 2 | 3;
+  /** The resolved `fast` and where it came from. */
+  fast: { requested: boolean; defaultedFrom: "request" | "format" };
+  /** What was applied and what was not. */
+  assumptions: string[];
+}
+```

package/docs/api/capture-jpeg-xl-tiles.md

@@ -0,0 +1,33 @@
+# capture/jpeg-xl-tiles.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.
+
+## createJxlOxideDngDecoder
+
+A {@link DngJpegXlDecoder} over jxl-oxide-wasm: `forceSrgb` off (the samples stay in the codestream's encoding), one render per
+tile, and the image object freed after it. Usage: `import init, * as jxl from "jxl-oxide-wasm"; await init();
+createJxlOxideDngDecoder(jxl)`.
+
+```ts
+export function createJxlOxideDngDecoder(module: JxlOxideModule): DngJpegXlDecoder;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DngJpegXlDecoder
+
+Decodes one JPEG XL codestream (a DNG strip or tile) to PNG bytes in the codestream's own colour encoding (no colour conversion).
+
+```ts
+export type DngJpegXlDecoder = (codestream: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+```
+
+## JxlOxideModule
+
+The part of the jxl-oxide-wasm module the adapter uses (its `JxlImage` class, after the module's `init`).
+
+```ts
+export interface JxlOxideModule {
+  JxlImage: new () => { feedBytes(bytes: Uint8Array): unknown; tryInit(): boolean; render(): { encodeToPng(): Uint8Array }; forceSrgb: boolean; free(): void };
+}
+```

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

@@ -0,0 +1,41 @@
+# capture/lossy-jpeg.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.
+
+## LossyJpegImage
+
+Decoded samples, interleaved by component within each line (line, x, component), 0..255.
+
+```ts
+export interface LossyJpegImage {
+  width: number;
+  height: number;
+  components: number;
+  /** "ycbcr-to-rgb" when three YCbCr components were converted to RGB; "none" otherwise. */
+  colorTransform: "ycbcr-to-rgb" | "none";
+  samples: Uint8Array;
+}
+```
+
+## LossyJpegLimits
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LossyJpegLimits {
+  /** Largest width x height x components accepted, checked before any sample buffer is allocated. */
+  maximumSamples: number;
+  /** An abbreviated table-specification stream (SOI, DQT/DHT, EOI) read before `bytes`, as DNG's JPEGTables tag (347) supplies. */
+  tables?: Uint8Array;
+}
+```
+
+## parseLossyJpeg
+
+Decodes one DCT JPEG stream (see the module notes). Every length, count and table index is checked against the buffer.
+
+```ts
+export function parseLossyJpeg(bytes: Uint8Array, limits: LossyJpegLimits): LossyJpegImage;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/capture-native-raw-development.md

@@ -136,7 +136,8 @@ RAW saturation handled before white balance. Counts are pixels or samples of the
 
 ```ts
 export interface RawHighlightDiagnostics {
-  mode: RawHighlightMode;
+  /** #602: "reconstruct-neighbors" from `simulateCapture`'s whole-image neighbor reconstruction. */
+  mode: RawHighlightMode | "reconstruct-neighbors";
   /** Output pixels with at least one contributing site at or above its white level, or flagged as saturated. */
   saturatedPixelCount: number;
   /** `clip`: WB-scaled samples clipped at the smallest gain. Always 0 for `reconstruct`. */

package/docs/api/core-execution-error.md

@@ -0,0 +1,43 @@
+# core/execution-error.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.
+
+## ImageKernelExecutionError
+
+Domain error for getting and running a backend. Input validation still throws the engine's existing errors.
+
+```ts
+export class ImageKernelExecutionError extends Error {
+  readonly code = "IMAGE_KERNEL_EXECUTION";
+  readonly reason: ImageKernelFailureReason;
+
+  constructor(reason: ImageKernelFailureReason, message: string) {
+    super(message);
+    this.name = "ImageKernelExecutionError";
+    this.reason = reason;
+  }
+}
+```
+
+## ImageKernelFailureReason
+
+Failure classes reported by {@link ImageKernelExecutionError}. `conformance-failed` (#481): a device failed the display view's
+run-time self-check with `gpu: "require"`. `quality-code-unavailable` (2.22.0, #594): on-demand full-quality code could not be
+loaded (for example a failed chunk download); `prepareQualityPaths()` rejects with it, a display-view render with `gpu: "require"`
+fails with it (with `gpu: "auto"` it runs the CPU reference), and a CPU request whose full-quality or opt-in code does not load
+fails with it (nothing is remembered: the next request tries again).
+
+```ts
+export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification" | "conformance-failed" |
+  "quality-code-unavailable";
+```
+
+## ImageKernelFallbackReason
+
+Why a requested `webgpu-f32` backend ran the CPU reference instead. `webgpu-disabled`: `setWebGpuEnabled(false)` in this realm.
+
+```ts
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "webgpu-disabled" | "adapter-unavailable" | "device-request-failed" |
+  "insufficient-limits" | "unsupported-platform-endianness";
+```

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.21.0" as const
+ENGINE_API_VERSION = "2.23.0" as const
 ```