@photivra/engine 1.4.0 → 2.0.0

package/docs/api/facade-chart-scenes.md

@@ -0,0 +1,240 @@
+# facade/chart-scenes.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.
+
+## calculatePointGridCenters
+
+Centres (frame units) of a point grid: one disk centred in each of columns × rows equal cells, row-major from the top-left.
+
+```ts
+export function calculatePointGridCenters(input: { columns: number; rows: number; aspect: number }): { u: number; v: number }[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateStepWedgeReflectances
+
+Step reflectances of a step wedge. `equal-density` spaces optical density D = -log10(R) evenly, which
+gives geometric reflectance steps, as on a photographic step tablet. `linear` spaces reflectance evenly.
+
+```ts
+export function calculateStepWedgeReflectances(input: { steps: number; minimumReflectance: number; maximumReflectance: number;
+  spacing: "equal-density" | "linear" }): number[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CHART_SCENE_DEFAULTS
+
+Engine-chosen chart parameters, each reported when the caller omitted it.
+
+```ts
+CHART_SCENE_DEFAULTS = Object.freeze({
+  uniform: Object.freeze({ reflectance: 0.18 }),
+  "slanted-edge": Object.freeze({ angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
+  "siemens-star": Object.freeze({ cycles: 36, radiusFraction: 0.9, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
+  "step-wedge": Object.freeze({ steps: 11, minimumReflectance: 0.03, maximumReflectance: 0.9, spacing: "equal-density" as const }),
+  "grey-ramp": Object.freeze({ minimumReflectance: 0.03, maximumReflectance: 0.9 }),
+  checkerboard: Object.freeze({ squaresAcross: 8, darkReflectance: 0.05, lightReflectance: 0.8 }),
+  "point-grid": Object.freeze({ columns: 5, rows: 3, radius: 0.01, pointReflectance: 0.9, backgroundReflectance: 0.02 }),
+  patches: Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 })
+})
+```
+
+## CHART_SCENE_PRESETS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CHART_SCENE_PRESETS: readonly ChartScenePresetId[] = Object.freeze(["uniform", "slanted-edge", "siemens-star",
+  "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches"] as const)
+```
+
+## CHART_SPECTRAL_RANGE_NANOMETERS
+
+Wavelength range every chart spectrum must cover (the facade's sensor quadrature range).
+
+```ts
+CHART_SPECTRAL_RANGE_NANOMETERS = Object.freeze({ minimum: 380, maximum: 780 })
+```
+
+## ChartReflectance
+
+A neutral (spectrally flat) reflectance in [0, 1], or a caller reflectance spectrum (values in [0, 1]).
+
+```ts
+export type ChartReflectance = number | ColorimetricSpectrum;
+```
+
+## ChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ChartScene = UniformChartScene | SlantedEdgeChartScene | SiemensStarChartScene | StepWedgeChartScene |
+  GreyRampChartScene | CheckerboardChartScene | PointGridChartScene | PatchChartScene;
+```
+
+## ChartScenePresetId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ChartScenePresetId = ChartScene["preset"];
+```
+
+## CheckerboardChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CheckerboardChartScene {
+  preset: "checkerboard";
+  /** Squares across the frame width, 2..256. Default 8. */
+  squaresAcross?: number;
+  darkReflectance?: number;
+  lightReflectance?: number;
+}
+```
+
+## GreyRampChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GreyRampChartScene {
+  preset: "grey-ramp";
+  /** Continuous ramp, linear in reflectance from left (minimum) to right (maximum). */
+  minimumReflectance?: number;
+  maximumReflectance?: number;
+}
+```
+
+## PatchChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PatchChartScene {
+  preset: "patches";
+  /** Caller reflectance per patch, row-major; the facade bundles no colour-chart data. 1..1024 patches. */
+  patches: readonly { patchId: string; reflectance: ChartReflectance }[];
+  /** Patches per row. Default ceil(sqrt(patch count)). */
+  columns?: number;
+  /** Gap between patches as a fraction of the cell size, [0, 0.5). Default 0.1. */
+  gapFraction?: number;
+  backgroundReflectance?: number;
+}
+```
+
+## PointGridChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PointGridChartScene {
+  preset: "point-grid";
+  /** Grid columns and rows of small disks centred in equal cells. Defaults 5 × 3. */
+  columns?: number;
+  rows?: number;
+  /** Disk radius in frame units (fraction of the frame half-width). Default 0.01. */
+  radius?: number;
+  pointReflectance?: number;
+  backgroundReflectance?: number;
+}
+```
+
+## resolveChartScene
+
+Validates a chart description and resolves every default. `aspect` is the frame height/width. Unknown
+fields are rejected so that a mistyped parameter never silently falls back to a default.
+
+```ts
+export function resolveChartScene(input: { scene: ChartScene; aspect: number }): ResolvedChartScene;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedChartScene
+
+A validated chart: every parameter resolved, plus which ones came from {@link CHART_SCENE_DEFAULTS}.
+
+```ts
+export interface ResolvedChartScene {
+  preset: ChartScenePresetId;
+  /** Fully resolved parameters (spectra are reported as `"caller-spectrum"`). */
+  parameters: Readonly<Record<string, unknown>>;
+  /** Names of parameters filled from defaults. */
+  defaultedParameters: readonly string[];
+  /** Frame aspect (height / width) the chart was resolved for. */
+  aspect: number;
+  /**
+   * Material index at a frame point (u right, v up). The index points into `materials`, starting at 0.
+   * Points outside the framed rectangle still evaluate (the pattern continues as defined), so blur and
+   * small framing differences stay well defined.
+   */
+  materialAt(u: number, v: number): number;
+  /** Reflectance materials: a neutral number or a prepared caller spectrum. */
+  materials: readonly ({ kind: "neutral"; reflectance: number } | { kind: "spectrum"; spectrum: PreparedColorimetricSpectrum })[];
+  /** Reflectance in [0, 1] at a frame point and wavelength (nm). */
+  reflectanceAt(u: number, v: number, wavelengthNanometers: number): number;
+}
+```
+
+## SiemensStarChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SiemensStarChartScene {
+  preset: "siemens-star";
+  /** Light/dark sector pairs around the star, 2..360. Default 36. */
+  cycles?: number;
+  /** Star radius as a fraction of the frame half-height, (0, 1]. Default 0.9. */
+  radiusFraction?: number;
+  darkReflectance?: number;
+  lightReflectance?: number;
+  /** Reflectance outside the star. Default 0.18. */
+  backgroundReflectance?: number;
+}
+```
+
+## SlantedEdgeChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SlantedEdgeChartScene {
+  preset: "slanted-edge";
+  /** Clockwise tilt of the edge from vertical, degrees, in (-45, 45). Default 5. */
+  angleDegrees?: number;
+  /** Left (dark) side reflectance. Default 0.15. */
+  darkReflectance?: number;
+  /** Right (light) side reflectance. Default 0.6 (4:1 with the default dark side). */
+  lightReflectance?: number;
+}
+```
+
+## StepWedgeChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface StepWedgeChartScene {
+  preset: "step-wedge";
+  /** Number of equal-width vertical steps from left (minimum) to right (maximum), 2..64. Default 11. */
+  steps?: number;
+  minimumReflectance?: number;
+  maximumReflectance?: number;
+  /** `equal-density` (geometric, default) or `linear` reflectance spacing. */
+  spacing?: "equal-density" | "linear";
+}
+```
+
+## UniformChartScene
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface UniformChartScene { preset: "uniform"; reflectance?: ChartReflectance }
+```

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

@@ -0,0 +1,122 @@
+# facade/scene-radiance.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.
+
+## CallerRadianceScene
+
+Caller absolute spectral radiance in W·m⁻²·sr⁻¹·nm⁻¹; the facade illuminant is not used.
+
+```ts
+export interface CallerRadianceScene { kind: "radiance-function"; sceneId: string; evaluate(point: Readonly<ScenePlanePoint>): number }
+```
+
+## CallerReflectanceScene
+
+Caller Lambertian reflectance (in [0, 1]) lit by the facade illuminant.
+
+```ts
+export interface CallerReflectanceScene { kind: "reflectance-function"; sceneId: string; evaluate(point: Readonly<ScenePlanePoint>): number }
+```
+
+## CaptureIlluminant
+
+Illuminant choices. CIE D65 is not bundled: its S0/S1/S2 basis tables must come from the caller
+(`daylight`). `planckian` is Planck's law; `cie-a` is CIE illuminant A from its defining formula.
+
+```ts
+export type CaptureIlluminant =
+  | "cie-a"
+  | { kind: "planckian"; temperatureKelvin: number }
+  | { kind: "cie-a" }
+  | { kind: "daylight"; correlatedColorTemperatureKelvin: number; basis: CieDaylightBasis }
+  | { kind: "spectrum"; spectrum: ColorimetricSpectrum; label?: string };
+```
+
+## createPlanarSceneRadianceProvider
+
+Public scene-preset provider. Places an engine chart (or a caller reflectance or radiance function) on
+a plane `distanceM` in front of the camera and `framedWidthM` wide (frame units u = ±1 at its edges),
+lit by `illuminant` at `illuminanceLux`. The returned `evaluateRadiance` and `evaluateApertureRadiance`
+follow the native environment RAW provider contract. They answer requests for scene `sceneId` and
+provider `providerProfileId`.
+
+```ts
+export function createPlanarSceneRadianceProvider(input: {
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  illuminant: CaptureIlluminant;
+  illuminanceLux: number;
+  distanceM: number;
+  framedWidthM: number;
+  /** Frame height / width. */
+  aspect: number;
+  sceneId: string;
+  providerProfileId: string;
+}): PlanarSceneRadianceProvider & { chart: ResolvedChartScene | null };
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W
+
+CIE maximum luminous efficacy for photopic vision, lm/W.
+
+```ts
+PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W = 683
+```
+
+## PlanarSceneRadianceProvider
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PlanarSceneRadianceProvider {
+  sceneId: string;
+  providerProfileId: string;
+  evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult;
+  evaluateApertureRadiance(request: Readonly<SceneRadianceEvaluationRequest>, ray: Readonly<SensorApertureRay>): SceneRadianceEvaluationResult;
+  /** Spectral radiance at a plane point (frame units), the same value the callbacks return. */
+  radianceAt(u: number, v: number, wavelengthNanometers: number): number;
+}
+```
+
+## resolveCaptureIlluminant
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export function resolveCaptureIlluminant(value: CaptureIlluminant): ResolvedCaptureIlluminant;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedCaptureIlluminant
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureIlluminant {
+  /** Short public description, for example "planckian-6500K". */
+  id: string;
+  description: string;
+  /** Relative spectral shape (arbitrary scale) over at least 380-780 nm. */
+  shape: PreparedColorimetricSpectrum;
+  /** Original spectrum, for colorimetric white-balance calculations. */
+  spectrum: ColorimetricSpectrum;
+}
+```
+
+## ScenePlanePoint
+
+A point of the scene plane passed to caller scene functions.
+
+```ts
+export interface ScenePlanePoint {
+  /** Metres on the plane, from the optical axis: +x right, +y up (as seen from the camera). */
+  xM: number;
+  yM: number;
+  /** The same point in frame units (u = ±1 at the left/right frame edges, v up on the same scale). */
+  u: number;
+  v: number;
+  wavelengthNanometers: number;
+}
+```

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

@@ -0,0 +1,324 @@
+# facade/simulate-capture.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.
+
+## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
+
+Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
+output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
+E = π·10·N²/(0.65·t·S·0.18) = π·80 000/11.7 ≈ 21 480.98 lux.
+
+```ts
+SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX = Math.PI * sosReferenceLuminance(DEFAULTS.fNumber, DEFAULTS.shutterSeconds, DEFAULTS.iso) /
+  GREY_CARD_REFLECTANCE
+```
+
+## SIMULATE_CAPTURE_FACADE_VERSION
+
+Version of how the facade builds requests. It changes whenever the same input would build a different request.
+
+```ts
+SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
+```
+
+## simulateCapture
+
+Simulates one still capture of a planar scene and returns the developed image, the packed RAW, the full
+underlying request/plan, provenance and every assumption made. See docs/QUICK_START.md.
+
+```ts
+export async function simulateCapture(options: SimulateCaptureOptions): Promise<SimulateCaptureResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## SimulateCaptureAssumption
+
+One decision the facade made: a default, a derived value or a fixed modelling choice.
+
+```ts
+export interface SimulateCaptureAssumption {
+  /** Dotted option path or modelling topic, for example "exposure.shutterSeconds" or "model.lens-psf". */
+  id: string;
+  kind: "default" | "derived" | "model";
+  value: unknown;
+  explanation: string;
+}
+```
+
+## SimulateCaptureBorderHandling
+
+`margin` renders extra native sites around the output, as far as the kernel reaches. `mirror` renders
+exactly the output and reads mirrored (reflect-101) copies of the missing border sites. Mirroring is
+checked to keep the CFA (colour filter array) pattern consistent.
+
+```ts
+export type SimulateCaptureBorderHandling = "margin" | "mirror";
+```
+
+## SimulateCaptureColorEncoding
+
+PNG colour encoding. `srgb` is the developed sRGB output. The others take the developed linear
+colour (camera → XYZ → linear sRGB/D65, unclipped) and convert it through CIE XYZ into the target
+primaries:
+- `display-p3`: Display P3 primaries (W3C CSS Color 4 `display-p3`; also SMPTE EG 432-1) with the
+  sRGB transfer function;
+- `rec2020`: ITU-R BT.2020 primaries and OETF.
+PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
+
+```ts
+export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
+```
+
+## SimulateCaptureDemosaic
+
+Built-in Bayer demosaic kernels (`createBuiltInBayerDemosaicProfiles`).
+
+```ts
+export type SimulateCaptureDemosaic = "bilinear";
+```
+
+## SimulateCaptureExposureMode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
+```
+
+## SimulateCaptureLensDistortion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureLensDistortion =
+  | { kind: "radial"; profile: RadialDistortionProfile }
+  | { kind: "brown-conrady"; profile: BrownConradyDistortionProfile };
+```
+
+## SimulateCaptureMotion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureMotion {
+  /** Constant camera angular velocity, rad/s, in the engine's pitch/yaw/roll convention. Missing axes are 0. */
+  angularVelocityRadPerSec?: { pitch?: number; yaw?: number; roll?: number };
+  /** Default "global". `rolling` derives the exposure schedule from the body's rolling readout declaration. */
+  shutter?: "global" | "rolling";
+  /** Rolling shutter only: time from the first to the last line over the simulated frame, in s. Default: the body's declared readout skew. */
+  rollingShutterSkewSeconds?: number;
+}
+```
+
+## SimulateCaptureOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureOptions {
+  /** Generic tier preset id or a full preset record (for example a modified copy of a catalog entry). Default "professional". */
+  camera?: GenericEquipmentTier | GenericEquipmentTierPreset;
+  lens?: {
+    /** Must lie in the lens capability (the generic primes are 50 mm). Default: the lens's shortest focal length. */
+    focalLengthMm?: number;
+    /** Aperture for manual and aperture-priority modes. Default 8. */
+    fNumber?: number;
+    /** Focus distance in metres. Default: the subject distance. */
+    focusDistanceM?: number;
+    /** Opt-in ideal circular-pupil ray sampling (defocus/depth of field). Default off (central ray only). */
+    pupilSampling?: { radialSamples: number; angularSamples: number };
+    /** Ideal lens projection (`LENS_PROJECTION_MODELS`). Default "rectilinear". Not combinable with pupilSampling. */
+    projection?: LensProjectionModel;
+    /** Caller-declared radial or Brown–Conrady distortion profile. Default none. Not combinable with pupilSampling. */
+    distortion?: SimulateCaptureLensDistortion;
+    /** Caller-declared radial relative-illumination (vignetting) profile, applied as environment field throughput. */
+    vignetting?: IlluminationVignettingProfile;
+    /**
+     * Caller sampled lens PSF, passed unchanged to the environment contract. Its focal length, f-number and
+     * focus must equal the resolved capture settings exactly. Not combinable with pupilSampling.
+     */
+    psf?: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
+  };
+  exposure?: {
+    /** Default "manual". */
+    mode?: SimulateCaptureExposureMode;
+    /** Default 100. */
+    iso?: number;
+    /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
+    shutterSeconds?: number;
+    /** Exposure compensation applied to the meter target, in stops. Default 0. */
+    compensationStops?: number;
+  };
+  /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  /** Distance from the camera to the scene plane in metres. Default 5. */
+  subjectDistanceM?: number;
+  /** Default: Planckian 6500 K (a blackbody stand-in for daylight; CIE D65 is not bundled). */
+  illuminant?: CaptureIlluminant;
+  /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
+  illuminanceLux?: number;
+  output?: {
+    /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
+    width?: number;
+    height?: number;
+    /** Default "srgb-8". */
+    format?: SimulateCaptureOutputFormat;
+    /** Default "identity". */
+    toneCurve?: SdrToneCurve;
+    /** Required by the luminance tone curves (see `SdrToneCurveParameters`). The facade does not make one up. */
+    toneCurveParameters?: SdrToneCurveParameters;
+    /** Default "clip". */
+    highlightMode?: RawHighlightMode;
+    /** Default "scene-illuminant". */
+    whiteBalance?: SimulateCaptureWhiteBalance;
+    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
+    jpegQuantizationStep?: number;
+    /** PNG only. Default "srgb". */
+    colorEncoding?: SimulateCaptureColorEncoding;
+    /** PNG only: 8 or 16 bits per sample. Default 8. */
+    bitDepth?: 8 | 16;
+    /**
+     * PNG SDR encodings only. Default "clip" (per-component clip to the target gamut). "perceptual" maps
+     * 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 "margin". */
+    borderHandling?: SimulateCaptureBorderHandling;
+    /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
+    dng?: { capturedAtUtc?: string };
+  };
+  /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
+  motion?: SimulateCaptureMotion;
+  sensor?: {
+    /** Pixel pitch in micrometres. Default 6. */
+    pixelPitchMicrometers?: number;
+    /** Maximum spectral quadrature subinterval in nm. Default 20. */
+    spectralStepNanometers?: number;
+    /** Temporal midpoint samples across the exposure. Default 1. */
+    temporalSampleCount?: number;
+    /** Noise seed (uint32). Default 1. */
+    noiseSeed?: number;
+  };
+  /** 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. */
+  onProgress?: (progress: SimulateCaptureProgress) => void;
+}
+```
+
+## SimulateCaptureOutputFormat
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
+```
+
+## SimulateCaptureProgress
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureProgress {
+  stage: "raw" | "white-balance" | "development" | "jpeg";
+  completedTileCount: number;
+  totalTileCount: number;
+}
+```
+
+## SimulateCaptureResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SimulateCaptureResult {
+  facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+  engineApiVersion: string;
+  image: {
+    width: number;
+    height: number;
+    format: SimulateCaptureOutputFormat;
+    /** Interleaved RGB, row by row from the top-left. sRGB-encoded (W3C CSS Color 4 sRGB; also IEC 61966-2-1) unless `colorEncoding` says otherwise. */
+    samples: Uint8Array | Uint16Array;
+    /** Baseline JPEG bytes when format is "jpeg". */
+    jpeg?: Uint8Array;
+    /** PNG file bytes when format is "png". */
+    png?: Uint8Array;
+    /** Encoding of `samples` and `png` when format is "png". */
+    colorEncoding?: SimulateCaptureColorEncoding;
+    /** Lossless uncompressed CFA DNG of the packed RAW when format is "dng" (`serializeNativeRawDng`); `samples` are then sRGB 8-bit. */
+    dng?: Uint8Array;
+  };
+  /** Packed native RAW (codes, black levels, saturation flags) as produced by the native environment RAW task. */
+  raw: NativeRawOutput;
+  plan: NativeRawPlan;
+  /** The complete underlying request. */
+  request: {
+    environmentRaw: NativeEnvironmentRawInput;
+    /** Rebuilds the exact physical site input the provider supplied for a native row-major index. */
+    siteInput(nativeIndex: number): SimulateEnvironmentSensorRawFrameInput["sites"][number];
+    development: Omit<NativeRawDevelopmentInput, "raw">;
+    whiteBalanceState: ResolvedWhiteBalanceState | null;
+  };
+  exposure: {
+    mode: SimulateCaptureExposureMode;
+    settings: { fNumber: number; shutterSeconds: number; iso: number };
+    /** Exposure value at ISO 100 of the settings, log2(N²/t). */
+    ev100: number;
+    meteredSceneLuminanceCdPerSquareMeter: number;
+    /** Full output of the existing exposure-mode resolver. */
+    resolution: unknown;
+  };
+  scene: {
+    sceneId: string;
+    preset: string;
+    parameters: Readonly<Record<string, unknown>>;
+    illuminant: { id: string; description: string; illuminanceLux: number };
+    distanceM: number;
+    /** Physical size of the framed scene plane, metres. */
+    framedWidthM: number;
+    framedHeightM: number;
+    /**
+     * SHA-256 of the canonical scene description, recorded as the capture source digest. Caller spectra (a
+     * `spectrum` or `daylight` illuminant, chart reflectance spectra) are part of the description: tabulated
+     * data exactly, function spectra sampled at 1 nm over 380-780 nm, plus the daylight basis datasetId.
+     * The body of a caller scene's evaluate function is not hashed.
+     */
+    sourceSha256: string;
+  };
+  diagnostics: {
+    providerEvaluationCount: number;
+    highlight: RawHighlightDiagnostics;
+    rendering: SdrRenderingResult["diagnostics"];
+    /** Present with output.gamutMapping "perceptual": pixels whose chroma or lightness the mapping changed. */
+    gamutMapping?: { method: "cielab-hue-preserving-chroma-compression"; kneeFraction: number; adjustedPixelCount: number; lightnessClippedPixelCount: number };
+    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number };
+  };
+  provenance: {
+    scientificStatus: "approximation";
+    cameraPresetId: string;
+    cameraPresetVersion: string;
+    evidence: readonly EvidenceProvenance[];
+    /** Existing engine contracts the facade composed, in execution order. */
+    composedContracts: readonly string[];
+    limitations: readonly string[];
+  };
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
+## SimulateCaptureWhiteBalance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureWhiteBalance =
+  | "scene-illuminant"
+  | "auto"
+  | "none"
+  | { kelvin: number; tint?: number }
+  | { channelGains: { red: number; green: number; blue: number } };
+```