@photivra/engine 2.21.0 → 2.23.0

package/docs/USAGE.md

@@ -3324,6 +3324,18 @@ void develop;
   value by 2^stops before demosaic and white balance. A site pushed to white clips and counts as saturated; the RAW
   codes are not changed. 0 develops byte for byte as before. The WebGPU accelerator rejects a non-zero push.
 - `extended-reinhard-luminance` takes `{ whiteLuminance }`, the luminance mapped to output white.
+- `gamutHandling: "desaturate-to-luminance"` (#601, 2.22.0; opt-in, also `simulateCapture`'s `output.gamutHandling`) moves a
+  pixel whose largest component exceeds 1 after the tone curve toward the gray of its own luminance until that component is 1,
+  keeping its luminance and hue; the default `"clip-components"` clips each component. The WebGPU SDR kernels refuse it.
+- The display view (`simulateDisplayView`, `prepareDisplayView`) renders the luminance tone curves, `highlightMode: "reconstruct"`
+  and the desaturation since 2.22.0 (#593), with fast rules on screen and full ones for `fast: false`
+  ([Display view, Coupled rendering](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#coupled-rendering-593-601)). Photivra's Standard look is
+  `{ exponent: 1.5, semiSaturation: 0.5009, whiteLuminance: 8 }` and its Flat look `{ exponent: 1, semiSaturation: 0.8465, whiteLuminance: 32 }`
+  for `naka-rushton-luminance` (18 % gray stays at 0.18; the engine's own looks, not a camera maker's).
+- `simulateCapture`'s `output.highlightMode: "reconstruct-neighbors"` (#602, 2.22.0; opt-in, an estimate) rebuilds clipped
+  channels from the color ratios around each clipped region: the ring's mean ratios with `fast` (the sRGB default), their harmonic
+  interpolation inward for exports and `fast: false`. Whole-image, so not with `output.region`; the display view renders it on the CPU and (since 2.23.0, #605) in its
+  WebGPU Speed and Quality kernels, fast and full.
 - `createPhotographicExportPair(input, { signal })` accepts an optional `AbortSignal`.
 
 ## Capture-mode profiles
@@ -7096,7 +7108,8 @@ See [Local POC Simulation API](https://github.com/Photivra/photivra/blob/main/do
 
 ## DNG import and PNG output
 
-- `parseDngRawImage` reads a DNG or TIFF-EP CFA/LinearRaw file (uncompressed or lossless JPEG, 8–16 bits). It returns the stored raw codes plus the CFA, black/white levels, active area, default crop, colour matrices, as-shot neutral and orientation. Nothing is applied to the codes.
+- `parseDngRawImage` reads a DNG or TIFF-EP CFA/LinearRaw file (uncompressed, lossless JPEG or, from 2.22.0, 8-bit lossy JPEG; 8–16 bits). It returns the stored raw codes plus the CFA, black/white levels, active area, default crop, colour matrices, as-shot neutral and orientation, and (2.22.0) the opcode lists, the profile gain table map, RGBTables, semantic masks and an `assumptions` list naming every rendering tag it does not apply. Nothing is applied to the codes. `importDngRawImage` (2.22.0) does the same asynchronously and also reads JPEG XL raw data through a decoder the application supplies (`createJxlOxideDngDecoder` over the jxl-oxide-wasm package, which the app installs and loads only when a JPEG XL DNG is opened; the engine does not depend on it); `size: "half"` gives a half-size LinearRaw preview and `maximumBytes` bounds the memory.
+- `developDngStageImage` (2.22.0) builds the DNG's linear stage image (linearization, black and white levels, OpcodeList1/2/3); `applyDngProfileGainTableMap` and `applyDngRgbTables` apply the phone rendering tags at their places in a development.
 - `serializePngImage` writes an 8- or 16-bit RGB PNG with an sRGB, ICC or cICP (Display P3, BT.2020; sRGB, BT.709 or linear transfer) colour description, and optional mDCV/cLLI display metadata. PQ and HLG are not part of 2.0 (see the patent review in `THIRD_PARTY.md`).
 
 See [DNG import and PNG output](https://github.com/Photivra/photivra/blob/main/docs/IMPORT_AND_PNG.md) for supported subsets, limits and sources.
@@ -7533,6 +7546,25 @@ for (const p of SENSOR_PROFILES) {
 }
 ```
 
+### Read noise and native-pixel figures (2.22.0, #595, #599)
+
+`sensor.readNoise` is the read noise of one **physical photosite**, as a sensor datasheet gives it, on a generic tier, a caller
+preset and a sensor profile alike (2.22.0; before, a tier took it as the rendered site's). A rendered site that stands for N
+photosites (pitch above the tier's 6 µm, or above a profile's own pitch) sums their read noise: it takes the value ×√N. Without
+`sensor.readNoise` a tier's site takes its 6 µm photosite's read noise ×√N in the same way (#599). Below one photosite the value is
+kept. `result.sensor` reports the rendered site; `result.sensor.native` one photosite (its `readNoiseElectrons` is the value you
+gave), with the EMVA 1288 and the 8 MP-normalized dynamic range
+([QUICK_START.md, "Native-pixel dynamic range"](QUICK_START.md#sensor-characteristics-555)).
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const r = await simulateCapture({ scene: { preset: "uniform" }, sensor: { pixelPitchMicrometers: 12, readNoise: { lowGainElectrons: 3 } }, fast: false });
+r.sensor.native.readNoiseElectrons;    // 3, one 6 µm photosite's (the value given)
+r.sensor.readNoise.lowGainElectrons;   // 6, the rendered 12 µm site's: 3 × √4
+r.sensor.native.emva1288.dynamicRangeStops;
+```
+
 ## Generic lens catalogue (#549)
 
 `GENERIC_LENS_CATALOGUE` lists the engine's 30 generic primes (17 professional, 13 consumer, "PV 50 1.2 Pro", "PV 50 1.8"; Photivra's
@@ -7547,7 +7579,8 @@ correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` appl
 ([quick start](QUICK_START.md#generic-lens-catalogue-549)); `fast: true` (or `lens: { catalogue: { kind, fast: true } }`) takes its
 fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures.
 `calculateLateralColorFringe({ lensId, activeImagingArea, pixelPitchMicrometers, fieldPosition? })` gives the lens's lateral color as a
-fringe width: the blue-minus-red image displacement in µm and pixels at a field position (default the corner; #580). Equations, tables and the
+fringe width: the blue-minus-red image displacement in µm and pixels at a field position (default the corner; #580); its `channelDispersion` for
+the capture's own channels comes from `calculateCameraChannelResponse({ illuminant })` (#591, full quality: a 5 nm grid by default). Equations, tables and the
 chart measurements: [LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
 
 ```ts
@@ -7861,6 +7894,27 @@ const print = await simulateCapture({
 console.log(print.scene.parameters.encoding, print.assumptions.some((a) => a.id === "scene.imagePlane")); // "srgb-8", true
 ```
 
+### Loading the full-quality code ahead of time (2.22, #594)
+
+The full-quality paths load on demand: a bundler that splits dynamic imports keeps their code out of the first load, and the
+first request that needs it fetches it: the CPU full-quality code (diffraction, the capture's AHD demosaic, `lens.defocus`
+bokeh shapes, cat's eye and large discs, lens projection and distortion, the display view's luminance tone curves,
+reconstruct and desaturation, `highlightMode: "reconstruct-neighbors"`), the opt-in features (`sensor.profile`,
+`illumination`, `motion.subject`) and the display view's GPU full-quality code (diffraction, AHD, defocus and image-plane
+prints with `prepareDisplayView(…, { gpu: "auto" | "require" })`). `prepareQualityPaths()` fetches all of it ahead of time,
+so that request does not wait. It is optional, changes no result, and is safe to call at any time: concurrent calls share one
+load, and later calls load nothing. If the code does not load, the promise rejects with `ImageKernelExecutionError` reason
+`quality-code-unavailable` and nothing is remembered; a GPU render in the meantime runs the CPU reference (the same full-quality
+result, slower) with `diagnostics.fast.execution.fallbackReason: "quality-code-unavailable"`, a CPU request whose code does not
+load fails with that error, and the next request tries again.
+
+```ts
+import { prepareQualityPaths } from "@photivra/engine";
+
+// For example when the user opens Export, where full-quality renders follow.
+await prepareQualityPaths().catch(() => undefined); // a failed preload is retried by the request that needs the code
+```
+
 **Representative light sources (2.22).** The engine's own [representative light sources](https://github.com/Photivra/photivra/blob/main/docs/LIGHT_SOURCES.md) are four relative spectra
 designed by Photivra: a tri-phosphor fluorescent tube and white LEDs of low and high color rendering at 4000 K and a warm one at
 2700 K, each "representative, not a named product". `createRepresentativeLightSourceIlluminant({ sourceId })` returns an
@@ -8009,14 +8063,13 @@ it: Vite builds workers as `iife` by default, so a worker that calls `prepareDis
 modules (`worker: { format: "es" }`, with `new Worker(url, { type: "module" })`) to keep it out. Measured sizes:
 [Bundle size](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#bundle-size).
 
-#### Sharing AHD correction states between workers
+#### AHD correction states (deprecated in 2.22.0)
 
-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])`.
+From 2.10 to 2.21, low-signal AHD display pixels read correction states that workers could exchange. 2.22.0 removes the
+correction (a labelled approximation remains; see "AHD at low signal" in
+[DISPLAY_VIEW.md](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#ahd-at-low-signal)), so there is nothing
+to exchange: workers render AHD views with no shared state. The exchange functions stay until 3.0.0 as checked no-ops;
+remove the calls.
 
 ```ts
 import { serializeDisplayViewCorrectionStates, bindDisplayViewCorrectionStates, prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
@@ -8024,19 +8077,13 @@ import { serializeDisplayViewCorrectionStates, bindDisplayViewCorrectionStates,
 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));
+const prepared = await prepareDisplayView(request);
+// Deprecated: null, no grid keys, no states, nothing stored.
+console.log(prepared.correctionKey(), (await prepared.collectCorrectionStates(part)).gridKeys.length);
+console.log(serializeDisplayViewCorrectionStates().length, bindDisplayViewCorrectionStates([]));
+// The view itself needs none of them.
+const view = await prepared.render(part);
+console.log(view.diagnostics.ahdCorrectedPixelCount); // always 0 since 2.22.0
 ```
 
 ### Facade 2.0 options: output, demosaic, optics and motion
@@ -8239,3 +8286,39 @@ console.log(outOfFocus.limitingFactor); // "defocus"
 - Demosaicing, sharpening, noise and motion are not included.
 
 See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#which-limits-detail-the-lens-or-the-sensor).
+
+## Content Credentials in exports (#165)
+
+`bindC2paManifestStore`, `calculateC2paDataHash` and `setC2paManifestStore` embed a C2PA Manifest Store in a JPEG, PNG or
+DNG export, hash the bytes the signature covers and write the signed store in place at the same length (C2PA 2.4 §10.4);
+`parseC2paManifestStore` finds a store already in a file, without verifying it. The application builds, signs and validates
+the manifest; the engine holds no keys and makes no network calls. Here a minimal one-IFD TIFF
+stands in for a DNG export, and the stores are only the C2PA framing around zero or one bytes, not real manifests:
+
+```ts
+import { bindC2paManifestStore, calculateC2paDataHash, parseC2paManifestStore, setC2paManifestStore } from '@photivra/engine';
+
+// A C2PA Manifest Store's outer framing (C2PA 2.4 §11.1.4.2) around `fill` bytes. A real store comes from the app's manifest builder.
+function framedStore(length: number, fill: number): Uint8Array {
+  const store = new Uint8Array(length).fill(fill), view = new DataView(store.buffer);
+  view.setUint32(0, length); store.set([0x6a, 0x75, 0x6d, 0x62], 4); // 'jumb' superbox
+  view.setUint32(8, 30); store.set([0x6a, 0x75, 0x6d, 0x64], 12); // 'jumd' description box
+  store.set([0x63, 0x32, 0x70, 0x61, 0, 0x11, 0, 0x10, 0x80, 0, 0, 0xaa, 0, 0x38, 0x9b, 0x71, 3, 0x63, 0x32, 0x70, 0x61, 0], 16); // C2PA UUID, label "c2pa"
+  view.setUint32(38, length - 38); store.set([0x6a, 0x75, 0x6d, 0x62], 42); // one child box filling the rest
+  return store;
+}
+const tiff = Uint8Array.of(0x49, 0x49, 42, 0, 8, 0, 0, 0, 1, 0, 0, 1, 4, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0);
+
+const bound = bindC2paManifestStore({ file: tiff, manifestStore: framedStore(1024, 0) });
+console.log(bound.binding.exclusions); // [{ start: 26, length: 4 }, { start: 40, length: 1024 }]: the entry's count field and the store
+const { hashHex } = await calculateC2paDataHash({ file: bound.bytes, exclusions: bound.binding.exclusions });
+// The app writes the exclusions and hashHex into its c2pa.hash.data assertion, signs, and builds the final store at 1,024 bytes.
+const signed = setC2paManifestStore({ file: bound.bytes, binding: bound.binding, manifestStore: framedStore(1024, 1) });
+const after = await calculateC2paDataHash({ file: signed, exclusions: bound.binding.exclusions });
+if (signed.length !== bound.bytes.length || after.hashHex !== hashHex) throw new Error('The signed file must keep its length and data hash');
+const found = parseC2paManifestStore({ file: signed }); // the store and the same binding, or null for a file without one
+if (found?.manifestStore[46] !== 1) throw new Error('The signed store must be found');
+```
+
+See [Content Credentials](https://github.com/Photivra/photivra/blob/main/docs/CONTENT_CREDENTIALS.md) for the byte layouts,
+the checks and what is still to be validated externally.

package/docs/api/capture-c2pa-embed.md

@@ -0,0 +1,177 @@
+# capture/c2pa-embed.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.
+
+## bindC2paManifestStore
+
+Embeds a placeholder C2PA Manifest Store in a JPEG, PNG or TIFF/DNG export and returns the new file with its hard binding:
+the exclusions for `c2pa.hash.data` and where the store sits (C2PA 2.4 §A.3.1, §A.3.2, §A.3.6, §18.5, §10.4; see the module
+notes). The input file is not changed. Only the first store of a file can be added; a file that already has one is rejected.
+
+```ts
+export function bindC2paManifestStore(input: BindC2paManifestStoreInput): C2paBoundFile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## BindC2paManifestStoreInput
+
+Input of `bindC2paManifestStore`.
+
+```ts
+export interface BindC2paManifestStoreInput {
+  /** A JPEG, a PNG, or a TIFF-based file such as a DNG, as written by the engine's exporters. It is read, never changed. */
+  file: Uint8Array;
+  /**
+   * The placeholder store (§10.4): a JUMBF C2PA Manifest Store sized for the final signature. For JPEG it may instead be the
+   * same store already split into APP11 segments (what the C2PA reference SDK's placeholder call returns), as long as that
+   * split is the one described above.
+   */
+  manifestStore: Uint8Array;
+}
+```
+
+## C2PA_ALGORITHMIC_MEDIA_SOURCE_TYPE
+
+IPTC digital source type for media created purely by an algorithm (https://cv.iptc.org/newscodes/digitalsourcetype/).
+
+```ts
+C2PA_ALGORITHMIC_MEDIA_SOURCE_TYPE = "http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia" as const
+```
+
+## C2PA_MANIFEST_STORE_MAXIMUM_BYTES
+
+Largest manifest store the engine embeds or reads, bytes (an engine limit, not a C2PA one).
+
+```ts
+C2PA_MANIFEST_STORE_MAXIMUM_BYTES = 33_554_432
+```
+
+## C2paBoundFile
+
+A file with a manifest store embedded, and its binding.
+
+```ts
+export interface C2paBoundFile { bytes: Uint8Array; binding: C2paHardBinding }
+```
+
+## C2paByteRange
+
+A byte range of a file: `start` is a zero-based offset, `length` a byte count.
+
+```ts
+export interface C2paByteRange { start: number; length: number }
+```
+
+## C2paDataHash
+
+SHA-256 over every byte of the file outside the exclusions, in file order (§18.5): the `hash` of `c2pa.hash.data`.
+
+```ts
+export interface C2paDataHash { alg: "sha256"; hash: Uint8Array; hashHex: string; hashedByteCount: number }
+```
+
+## C2paFoundManifestStore
+
+A manifest store found in a file (`parseC2paManifestStore`): its binding and a copy of the store's JUMBF bytes.
+
+```ts
+export interface C2paFoundManifestStore { binding: C2paHardBinding; manifestStore: Uint8Array }
+```
+
+## C2paHardBinding
+
+Where the manifest store sits in a file and which bytes the data hash excludes. Plain data: it can be kept, sent to a
+worker or serialized, and must be passed back unchanged to `setC2paManifestStore`.
+
+```ts
+export interface C2paHardBinding {
+  /** `image/jpeg`, `image/png`, or for TIFF files `image/dng` when the main IFD has DNGVersion (50706), otherwise `image/tiff`. */
+  mediaType: "image/jpeg" | "image/png" | "image/dng" | "image/tiff";
+  /** Length of the file with the store embedded, bytes. */
+  fileLength: number;
+  /** The `exclusions` of the `c2pa.hash.data` assertion, ascending and non-overlapping (§18.5). */
+  exclusions: readonly C2paByteRange[];
+  /** JPEG: every C2PA APP11 segment, markers and length fields included. PNG: the whole caBX chunk. TIFF/DNG: the store's own bytes. */
+  manifestRegion: C2paByteRange;
+  /** Length of the JUMBF manifest store itself, bytes. A replacement store must have exactly this length. */
+  manifestStoreLength: number;
+}
+```
+
+## calculateC2paDataHash
+
+SHA-256 over every byte of a file outside the given exclusions, in file order: the value of `hash` in a `c2pa.hash.data`
+assertion with `alg` "sha256" (C2PA 2.4 §18.5). It uses Web Crypto (`crypto.subtle`, browsers in secure contexts and
+Node 22+). The bytes outside the exclusions are copied once into one array before hashing.
+
+```ts
+export async function calculateC2paDataHash(input: CalculateC2paDataHashInput): Promise<C2paDataHash>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## CalculateC2paDataHashInput
+
+Input of `calculateC2paDataHash`.
+
+```ts
+export interface CalculateC2paDataHashInput {
+  /** The bound file. */
+  file: Uint8Array;
+  /** The binding's exclusions (or any ascending, non-overlapping ranges inside the file). */
+  exclusions: readonly C2paByteRange[];
+}
+```
+
+## parseC2paManifestStore
+
+Finds the C2PA Manifest Store embedded in a JPEG (APP11), PNG (caBX) or TIFF/DNG (tag 52545) and returns its location as a
+binding (the exclusions the engine's own writer uses for that format) and a copy of the store. It checks the file's structure
+and the store's outer framing only: it does not read the manifests, check the data hash or verify any signature. The
+manifest's own `c2pa.hash.data` assertion is what a validator uses; this binding is what `setC2paManifestStore` needs.
+
+```ts
+export function parseC2paManifestStore(input: ParseC2paManifestStoreInput): C2paFoundManifestStore | null;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ParseC2paManifestStoreInput
+
+Input of `parseC2paManifestStore`.
+
+```ts
+export interface ParseC2paManifestStoreInput {
+  /** A JPEG, PNG or TIFF-based file such as a DNG. It is read, never changed. */
+  file: Uint8Array;
+}
+```
+
+## setC2paManifestStore
+
+Writes the final, signed manifest store over the placeholder of a bound file (C2PA 2.4 §10.4.4). The store must have
+exactly the placeholder's length, so the file's length, every offset and every byte outside the exclusions stay the same
+and the data hash computed before signing still holds. The binding is checked against the file first. The new store goes
+into the file's existing segments or chunk as they are (for PNG the chunk CRC is recomputed; it is inside the exclusion).
+
+```ts
+export function setC2paManifestStore(input: SetC2paManifestStoreInput): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SetC2paManifestStoreInput
+
+Input of `setC2paManifestStore`.
+
+```ts
+export interface SetC2paManifestStoreInput {
+  /** The bound file (`C2paBoundFile.bytes`). It is read, never changed. */
+  file: Uint8Array;
+  /** The binding `bindC2paManifestStore` (or `parseC2paManifestStore`) returned for it. */
+  binding: C2paHardBinding;
+  /** The final, signed store: exactly `binding.manifestStoreLength` bytes, as JUMBF or (JPEG) in the same APP11 split. */
+  manifestStore: Uint8Array;
+}
+```

package/docs/api/capture-dng-import.md

@@ -4,18 +4,31 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 ## DNG_IMPORT_LIMITS
 
-Upper bound for `maximumPixels`. 200 MP (megapixels) of 16-bit codes is 400 MB.
+Upper bound for `maximumPixels`: 200 MP (megapixels) of 16-bit codes is 400 MB. `maximumBytes` bounds the estimated peak memory
+of the import (default 1 GiB, at most 4 GiB).
 
 ```ts
-DNG_IMPORT_LIMITS = Object.freeze({ defaultMaximumPixels: 64_000_000, maximumPixels: 200_000_000, defaultMaximumIfds: 64, maximumIfds: 1024 })
+DNG_IMPORT_LIMITS = Object.freeze({ defaultMaximumPixels: 64_000_000, maximumPixels: 200_000_000, defaultMaximumIfds: 64, maximumIfds: 1024,
+  defaultMaximumBytes: 1_073_741_824, maximumBytes: 4_294_967_296 })
 ```
 
 ## DNG_IMPORT_SCHEMA_VERSION
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+1.1.0 (2.22.0): lossy JPEG and JPEG XL raw data, opcode lists, profile maps, semantic masks, `scale`, `assumptions`.
 
 ```ts
-DNG_IMPORT_SCHEMA_VERSION = "1.0.0" as const
+DNG_IMPORT_SCHEMA_VERSION = "1.1.0" as const
+```
+
+## DngImportAsyncInput
+
+{@link importDngRawImage}'s input: {@link DngImportInput} plus the JPEG XL decoder a 52546 file needs.
+
+```ts
+export interface DngImportAsyncInput extends DngImportInput {
+  /** Decodes one JPEG XL strip or tile to PNG (`createJxlOxideDngDecoder`). Needed only for JPEG XL raw data or masks. */
+  jpegXlDecoder?: DngJpegXlDecoder;
+}
 ```
 
 ## DngImportInput
@@ -29,9 +42,31 @@ export interface DngImportInput {
   maximumPixels?: number;
   /** Total IFDs (main chain plus SubIFDs) visited. Default 64, at most 1024. */
   maximumIfds?: number;
+  /**
+   * Estimated peak memory of the import, bytes (the codes, the largest strip or tile's decode buffers and its decoder's working
+   * memory; see docs/IMPORT_AND_PNG.md, "Memory"), checked before any image allocation. Default 1 073 741 824 (1 GiB), at most 4 GiB.
+   */
+  maximumBytes?: number;
+  /**
+   * "half": a half-size preview of a LinearRaw image, each output pixel the rounded mean of a 2 × 2 block of stored codes, decoded
+   * strip by strip (a quarter of the codes' memory). Areas, crops and black-level deltas are halved; CFA images are refused.
+   * Default "full".
+   */
+  size?: "full" | "half";
 }
 ```
 
+## importDngRawImage
+
+{@link parseDngRawImage} for every supported compression, JPEG XL included: each JPEG XL strip or tile goes to `jpegXlDecoder` in
+turn (one at a time, so only one tile's decoder memory is held), and its PNG is read at the DNG's bit depth (jpeg-xl-tiles.ts).
+
+```ts
+export async function importDngRawImage(input: DngImportAsyncInput): Promise<ImportedDngRaw>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
 ## ImportedDngBlackLevel
 
 Black level (the code for zero light) pattern, from BlackLevel, BlackLevelRepeatDim and BlackLevelDeltaH/V. Origin is the active-area top-left.
@@ -83,7 +118,14 @@ export interface ImportedDngRaw {
   height: number;
   samplesPerPixel: number;
   bitsPerSample: number;
-  compression: "uncompressed" | "lossless-jpeg";
+  compression: "uncompressed" | "lossless-jpeg" | "lossy-jpeg" | "jpeg-xl";
+  /**
+   * True when the raw data went through a lossy coder: lossy JPEG always; JPEG XL when JXLDistance (52553) is above 0 or absent
+   * (the file then does not say it is lossless).
+   */
+  lossySource: boolean;
+  /** 1, or 0.5 for a `size: "half"` preview (every geometry field is already halved). */
+  scale: 1 | 0.5;
   photometricInterpretation: "cfa" | "linear-raw";
   /** Stored raw codes, row-major then sample, length width x height x samplesPerPixel. */
   codes: Uint16Array;
@@ -107,6 +149,23 @@ export interface ImportedDngRaw {
   asShotNeutral: number[] | null;
   /** RawDataUniqueID as 32 lowercase hex digits, or null. */
   rawDataUniqueId: string | null;
+  /** ForwardMatrix1/2 (white-balanced camera → XYZ D50), row-major 3 x colorPlanes, or null. */
+  forwardMatrix1: number[] | null;
+  forwardMatrix2: number[] | null;
+  /** BaselineExposure plus BaselineExposureOffset (stops), or null when neither is present. */
+  baselineExposure: number | null;
+  /** OpcodeList1/2/3 (raw IFD), parsed but not applied (`developDngStageImage` applies them), or null when absent. */
+  opcodeList1: DngOpcode[] | null;
+  opcodeList2: DngOpcode[] | null;
+  opcodeList3: DngOpcode[] | null;
+  /** ProfileGainTableMap2 (IFD 0), else ProfileGainTableMap (raw IFD), or null; applied by `applyDngProfileGainTableMap`. */
+  profileGainTableMap: DngProfileGainTableMap | null;
+  /** RGBTables (IFD 0), or null; applied by `applyDngRgbTables`. */
+  rgbTables: DngRgbTables | null;
+  /** Decoded semantic masks, for `applyDngRgbTables`. */
+  semanticMasks: ImportedDngSemanticMask[];
+  /** What the import did not do: tags present but not returned or applied, masks not decoded, lossy sources, inferred layouts. */
+  assumptions: string[];
 }
 ```
 
@@ -118,14 +177,31 @@ Half-open raster rectangle in stored-image pixel coordinates (+X right, +Y down)
 export interface ImportedDngRect { x: number; y: number; width: number; height: number }
 ```
 
+## ImportedDngSemanticMask
+
+A decoded semantic mask (DNG 1.6 SemanticName, NewSubFileType 0x10004, PhotometricInterpretation 52527).
+
+```ts
+export interface ImportedDngSemanticMask {
+  name: string;
+  /** SemanticInstanceID, or null. */
+  instanceId: string | null;
+  width: number;
+  height: number;
+  /** Mask values 0..1 (code / (2^bits − 1)), row-major. */
+  data: Float32Array;
+}
+```
+
 ## parseDngRawImage
 
-Parse one DNG or TIFF-EP file and decode its primary CFA or LinearRaw image (the first IFD with
-NewSubFileType 0 and PhotometricInterpretation 32803 or 34892, in IFD-chain then SubIFD order).
+Parse one DNG or TIFF-EP file and decode its primary CFA or LinearRaw image (the first IFD with NewSubFileType 0 and
+PhotometricInterpretation 32803 or 34892, in IFD-chain then SubIFD order), synchronously.
 
-Supported raw data: Compression 1 at 8..16 bits/sample (8 bits as bytes, 16 bits in the file byte
-order, other depths packed MSB-first with byte-aligned rows, per DNG BitsPerSample) and Compression 7
-lossless Huffman JPEG (T.81 Annex H) in strips or tiles, chunky planar configuration only.
+Supported raw data: Compression 1 at 8..16 bits/sample (8 bits as bytes, 16 bits in the file byte order, other depths packed
+MSB-first with byte-aligned rows, per DNG BitsPerSample), Compression 7 lossless Huffman JPEG (T.81 Annex H) and Compression 34892
+8-bit lossy JPEG (T.81 sequential DCT), in strips or tiles, chunky planar configuration only. JPEG XL (52546) needs
+{@link importDngRawImage}; a JPEG XL semantic mask is skipped here and named in `assumptions`.
 
 ```ts
 export function parseDngRawImage(input: DngImportInput): ImportedDngRaw;

package/docs/api/capture-dng-opcodes.md

@@ -0,0 +1,93 @@
+# capture/dng-opcodes.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.
+
+## applyDngOpcodes
+
+Applies an opcode list to a stage image in place (WarpRectilinear returns a new buffer in `image.data`). Returns one assumption
+per opcode: what was applied, or why it was not.
+
+```ts
+export function applyDngOpcodes(image: DngStageImage, opcodes: readonly DngOpcode[], options: ApplyDngOpcodesOptions): string[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ApplyDngOpcodesOptions
+
+Options of {@link applyDngOpcodes}.
+
+```ts
+export interface ApplyDngOpcodesOptions {
+  /** 1, 2 or 3: the list's stage (for the report). */
+  stage: 1 | 2 | 3;
+  /**
+   * WarpRectilinear resampling: false (full quality) uses cubic convolution (Keys, a = −0.75, the DNG SDK's kernel); true uses
+   * bilinear interpolation (fast). Registered as "dngImport.warpRectilinear" in SIMULATE_CAPTURE_FAST_METHODS.
+   */
+  fast: boolean;
+  /** 1, or 0.5 for a half-size image: pixel-coordinate parameters are scaled; pitched areas and bad pixels are then not applied. */
+  scale?: 1 | 0.5;
+}
+```
+
+## DngOpcode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DngOpcode {
+  id: number;
+  /** The specification's name, or "Unknown". */
+  name: string;
+  dngVersion: [number, number, number, number];
+  /** Flag bit 0: a reader may skip it. */
+  optional: boolean;
+  /** Flag bit 1: may be skipped for preview-quality rendering. */
+  previewSkip: boolean;
+  /** Decoded parameters of an applied opcode; null for one this reader does not apply. */
+  parameters: DngOpcodeParameters | null;
+}
+```
+
+## DngOpcodeArea
+
+The rectangle, plane range and pitch an area-based opcode acts on (stage pixel coordinates, bottom and right exclusive).
+
+```ts
+export interface DngOpcodeArea { top: number; left: number; bottom: number; right: number; plane: number; planes: number; rowPitch: number; colPitch: number }
+```
+
+## DngOpcodeParameters
+
+Opcode parameters, by opcode.
+
+```ts
+export type DngOpcodeParameters =
+  | { opcode: "WarpRectilinear"; planes: { radial: [number, number, number, number]; tangential: [number, number] }[]; centerX: number; centerY: number }
+  | { opcode: "FixVignetteRadial"; coefficients: [number, number, number, number, number]; centerX: number; centerY: number }
+  | { opcode: "FixBadPixelsConstant"; constant: number; bayerPhase: number }
+  | { opcode: "FixBadPixelsList"; bayerPhase: number; points: [number, number][]; rects: [number, number, number, number][] }
+  | { opcode: "MapTable"; area: DngOpcodeArea; table: Uint16Array }
+  | { opcode: "MapPolynomial"; area: DngOpcodeArea; coefficients: number[] }
+  | { opcode: "GainMap"; area: DngOpcodeArea; pointsV: number; pointsH: number; spacingV: number; spacingH: number; originV: number; originH: number; mapPlanes: number; gains: Float32Array }
+  | { opcode: "DeltaPerRow" | "DeltaPerColumn" | "ScalePerRow" | "ScalePerColumn"; area: DngOpcodeArea; values: Float32Array };
+```
+
+## DngStageImage
+
+A stage image: interleaved (row, column, plane), normalized values.
+
+```ts
+export interface DngStageImage { width: number; height: number; planes: number; data: Float32Array }
+```
+
+## parseDngOpcodeList
+
+Parses an opcode list (the tag's bytes). Every count and length is checked against the bytes before allocation.
+
+```ts
+export function parseDngOpcodeList(bytes: Uint8Array): DngOpcode[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.