@photivra/engine 2.20.0 → 2.22.0

package/docs/USAGE.md

@@ -3324,6 +3324,17 @@ 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.
 - `createPhotographicExportPair(input, { signal })` accepts an optional `AbortSignal`.
 
 ## Capture-mode profiles
@@ -7096,7 +7107,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.
@@ -7146,6 +7158,7 @@ console.log(png.length, same);
 See [Print planning](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md) for a complete, strict packed example and the exact-ratio integer policy.
 
 - `calculatePrintPlan()` says whether the native sampling is enough, and gives a compatible minimum file raster.
+- `fit: { kind: "contain", paperOrientation }` (2.22.0) fits the whole image inside paper of another shape and reports the borders ([Contain fit](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md#integer-policy-fit-and-sufficiency)).
 - `calculatePrintSizeLimit()` distinguishes finite, unbounded and unavailable sampling limits.
 - `calculatePrintSizeLimitWithBlurAndNoise()` (2.20.0) gives the largest print at a viewing distance that still looks sharp and clean, counting blur and noise as well as pixels, and names the limiting factor ([Print size limit with blur and noise](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md#print-size-limit-with-blur-and-noise)). An approximation.
 - Print quality and delivery are not assessed.
@@ -7512,6 +7525,45 @@ console.log(calculateGeometricFocusBreathing({
 }).value.deltaDegrees);
 ```
 
+## Sensor profiles (#554)
+
+`SENSOR_PROFILES` lists eight representative sensors (full frame, APS-C, medium format and a large phone sensor; BSI,
+stacked and front-illuminated; 2010s and 2020s) whose values come from published specifications, values derived from them
+or labelled design values, with no maker or product named. `simulateCapture({ sensor: { profile: record } })` simulates one
+(the record is checked strictly; `resolveSensorProfile(id)` finds one by id):
+it replaces the body's ISO range, readout regimes, readout time and fixed-pattern noise, and the #555 characteristics
+override it one at a time. `resolveSensorProfile(id)` returns one profile; `SENSOR_PROFILE_ISO_ANCHOR` is the ISO anchor its base ISO is re-rated from. Values, sources and the ISO
+rating: [SENSOR_PROFILES.md](https://github.com/Photivra/photivra/blob/main/docs/SENSOR_PROFILES.md).
+
+```ts
+import { SENSOR_PROFILES, simulateCapture } from "@photivra/engine";
+
+for (const p of SENSOR_PROFILES) {
+  // fast: false (full quality, as the calculator asks) computes the mid-gray noise figure.
+  const r = await simulateCapture({ scene: { preset: "uniform" }, fast: false, sensor: { profile: p }, exposure: { mode: "manual", iso: 3200, shutterSeconds: 1 / 4000 } });
+  console.log(p.name, r.sensor.dynamicRangeStops.toFixed(1), r.sensor.midGrey?.snr.toFixed(1));
+}
+```
+
+### 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
@@ -7524,7 +7576,10 @@ correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` appl
 `output.lensCorrections` (#570; never to the RAW or the DNG), and which a DNG can carry for RAW editors as optional DNG opcodes with
 `output.dng.lensCorrectionOpcodes` (#587; the RAW codes unchanged). `simulateCapture` renders a catalogue lens with `lens.catalogue`
 ([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. Equations, tables and the
+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); 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
@@ -7790,6 +7845,13 @@ including the whole-image stages `output.diffractionCorrection` and `output.shar
 bytes as a whole-frame `simulateCapture()` and per-row progress (`diffraction-correction`, `sharpening`). See
 [Quick start, Developing a capture rendered in parts](QUICK_START.md#developing-a-capture-rendered-in-parts-571).
 
+`simulateExposureBuildUp(options, { fractions })` (#534) renders fractions of one exposure as one accumulating process. Each
+fraction's expected signal is its own capture at the elapsed time, so camera rotation, a moving subject and mixed lighting are
+included. Its photo and dark counts are binomial splits of the next fraction's, so they build up in place. Each fraction is
+clipped at the full well, read out once with its own read noise and developed as its own photo. The fraction at 1 is
+`simulateCapture(options)` byte for byte. Only the sRGB sample formats are accepted (on screen). See
+[Quick start, Exposure build-up](QUICK_START.md#exposure-build-up-534).
+
 ### Color charts (2.14)
 
 The engine's own [color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md) are reflectance spectra lit by the capture's illuminant. Draw the
@@ -7810,6 +7872,54 @@ const sky = getColorPatchSet().patches.find((p) => p.patchId === "sky-blue");
 console.log(tungsten.scene.parameters.patchSet, sky?.code, sky?.name, sky?.reference.cielabD65); // "PV-M1", "Midday Sky"
 ```
 
+### A photo as a print (2.21)
+
+An [image-plane scene](https://github.com/Photivra/photivra/blob/main/docs/IMAGE_PLANE.md) (#581) puts an sRGB (8- or 16-bit) or linear image in front of the camera as a flat matte
+print. Each pixel becomes a smooth reflectance spectrum in [0, 1] that gives back its sRGB under CIE D65. Under other lights the print's colors are an approximation.
+`chartSize` sets the print's size (its height follows the image). Without it the print is fitted inside the frame. `prepareDisplayView` renders it on WebGPU in the Speed path.
+`prepareImagePlaneScenes()` loads the scene's module first, so bundles that never print a photo do not carry it.
+
+```ts
+import { prepareImagePlaneScenes, simulateCapture } from "@photivra/engine";
+
+await prepareImagePlaneScenes(); // loads the scene's module (a lazy chunk) once
+const width = 2, height = 1, data = Uint8Array.of(255, 255, 255, 30, 60, 200);
+const print = await simulateCapture({
+  scene: { kind: "image-plane", sceneId: "snapshot", image: { width, height, channels: 3, encoding: "srgb-8", data }, paper: { whiteReflectance: 0.9 } },
+  chartSize: { widthM: 0.1 },
+  subjectDistanceM: 0.4,
+  output: { width: 32, height: 16 }
+});
+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
+`illuminant` (`{ kind: "spectrum", spectrum, label }`); under the two 4000 K LEDs the color patches differ by up to ΔE00 5.9 while
+the neutrals stay neutral. Use `sensor.spectralStepNanometers: 5`. The page has a runnable example.
+
 In `aperture-priority` mode, the shutter comes from the meter (CIPA DC-004 relations S = 10/H and H = 0.65·L·t/N²) through
 `resolveAperturePriorityExposureMode()`.
 `exposure.standardExposureDeviationStops` is the exposure used minus the standard exposure for the metered luminance L, in stops,
@@ -7866,6 +7976,28 @@ The chart presets are also available on their own:
 - `createPlanarSceneRadianceProvider()` turns a chart into an `evaluateRadiance` callback for the native
   environment RAW contract.
 
+### Mixed lighting (2.22, #550)
+
+`illumination` lights the chart with two or more sources blended across it (a linear gradient, a radial falloff or regions),
+for example window daylight on one side and a lamp on the other. The frame center's light sets the grey-card meter and its
+strongest source the `"scene-illuminant"` white balance; both are reported in `assumptions`. See
+[Mixed lighting](https://github.com/Photivra/photivra/blob/main/docs/MIXED_ILLUMINATION.md) for the model and every field.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const lampPool = await simulateCapture({
+  scene: { preset: "step-wedge" },
+  exposure: { mode: "aperture-priority", metering: "grey-card" },
+  illumination: {
+    sources: [{ illuminant: "cie-a", illuminanceLux: 500 }, { illuminant: { kind: "planckian", temperatureKelvin: 6500 }, illuminanceLux: 20000 }],
+    blend: { kind: "radial", radius: 0.8, stops: [0.25, 1] }
+  },
+  output: { width: 32, height: 16 }
+});
+console.log(lampPool.assumptions.find((a) => a.id === "output.whiteBalanceSource")?.value); // { source: 0, illuminant: "cie-a" }
+```
+
 ### Display view of a capture
 
 `simulateDisplayView(options, view)` takes a capture request and a display size and returns the real
@@ -7930,14 +8062,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";
@@ -7945,19 +8076,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
@@ -8051,6 +8176,18 @@ const rolling = await simulateCapture({ scene: { preset: "checkerboard" }, motio
 console.log(rolling.request.siteInput(7 * 8).charge.completenessProfile.startOffsetSecondsFromOpeningReference);
 ```
 
+`motion.subject` (2.22.0) moves the subject instead: the whole scene, or one `region` of it over a still background,
+at `velocityMPerSec` on the scene plane, optionally rotating at `angularVelocityRadPerSec` about the optical axis. It
+uses the same temporal midpoints, so a rolling shutter skews the moving subject. The display view renders sideways
+motion under a global shutter and refuses the rest. See [Subject motion](QUICK_START.md#subject-motion).
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const moving = await simulateCapture({ scene: { preset: "slanted-edge" }, motion: { subject: { velocityMPerSec: { x: 0.5 } } }, output: { width: 8, height: 8 } });
+console.log(moving.assumptions.find((a) => a.id === "motion.subject")?.value);
+```
+
 ## Equivalent f-number, sensor area and blur as a share of the frame
 
 `calculateSensorEquivalence()` says what a lens on one sensor corresponds to on a 36 × 24 mm frame (or on a `reference` you pass). Call it once per sensor to fill a lens table:
@@ -8148,3 +8285,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;