@photivra/engine 2.9.0 → 2.11.1

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

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

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

@@ -82,7 +82,8 @@ export interface ChartSizeOption {
 
 ## createPlanarSceneRadianceProvider
 
-Public scene-preset provider. Places an engine chart (or a caller reflectance or radiance function) on
+Public scene-preset provider. Places an engine chart (or a declared `material-layers` scene, #491, evaluated as
+its `callerScene`; or a caller reflectance, radiance or material 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
@@ -90,7 +91,7 @@ provider `providerProfileId`.
 
 ```ts
 export function createPlanarSceneRadianceProvider(input: {
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   distanceM: number;

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

@@ -30,7 +30,9 @@ export interface DisplayViewResult {
    * milliseconds (diagnostic only; never affects the samples).
    */
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
-    timingsMs: { view: number; total: number } };
+    timingsMs: { view: number; total: number };
+    /** #395: exact or fast, as requested and as run; 2.11 (#481): plus `execution`, where the render ran (see {@link DisplayViewFastReport}). */
+    fast: DisplayViewFastReport };
   provenance: { scientificStatus: "approximation"; cameraPresetId: string; cameraPresetVersion: string; evidence: readonly EvidenceProvenance[];
     composedContracts: readonly string[]; limitations: readonly string[] };
   /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
@@ -94,7 +96,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-  "lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
   "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -118,6 +120,16 @@ Version of how the facade builds requests. It changes whenever the same input wo
 SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
 ```
 
+## SIMULATE_CAPTURE_FAST_OPTIONS
+
+The options that take the exact-or-fast flag (#395), in the path style of {@link SIMULATE_CAPTURE_COST_OPTIONS}: each accepts
+the record form with `fast` and is reported in `diagnostics.fast.applied` when it runs. Every one of them takes the flag,
+whether or not it has a fast method yet; one without runs exact and reports `false`.
+
+```ts
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+```
+
 ## SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS
 
 Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform.
@@ -193,6 +205,14 @@ edge-directed method that reduces zipper and false colour on sharp edges.
 export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
+## SimulateCaptureDemosaicRecord
+
+`output.demosaic` as a record (#395): the demosaic and its `fast` override (see {@link SimulateCaptureOptions.fast}).
+
+```ts
+export interface SimulateCaptureDemosaicRecord { kind: SimulateCaptureDemosaic; fast?: boolean }
+```
+
 ## SimulateCaptureDngPart
 
 One part of a whole-frame DNG (#391): a region render's packed RAW and where its native sites lie (`result.raw`, `result.region`).
@@ -212,6 +232,29 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
 ```
 
+## SimulateCaptureFastOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[number];
+```
+
+## SimulateCaptureFastReport
+
+`diagnostics.fast` of a capture or display view (#395): what was asked for and what ran.
+
+```ts
+export interface SimulateCaptureFastReport {
+  /** True when `fast: true` was given at the top level or in any option's record. */
+  requested: boolean;
+  /** Each fast-capable option that ran, in {@link SIMULATE_CAPTURE_FAST_OPTIONS} order: true where its fast method ran. */
+  applied: Readonly<Partial<Record<SimulateCaptureFastOption, boolean>>>;
+  /** `engine-reference` when every option ran exact; `approximation-with-a-priori-bound` when any fast method ran (the WebGPU execution record's values). */
+  assurance: "engine-reference" | "approximation-with-a-priori-bound";
+}
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -280,6 +323,17 @@ export interface SimulateCaptureOptions {
      * the longest spectral node, capped at 32 sites. Not combinable with `psf` or `pupilSampling`. Default off.
      */
     diffraction?: SimulateCaptureLensDiffraction;
+    /**
+     * Opt-in (#492): defocus of the flat scene plane when `focusDistanceM` differs from the subject distance, as a
+     * geometric disc (`model: "geometric-disc"`): the thin-lens blur circle of an ideal uniform circular pupil
+     * (`calculateDefocusCircle`), an approximation. The blur diameter is recorded in the `lens.defocus` assumption.
+     * `simulateCapture` renders the blur as an object-space convolution of the scene radiance on the site lattice and
+     * `simulateDisplayView` as a site kernel in its expected signal; with `diffraction` each spectral node's diffraction
+     * kernel is convolved with the disc (a further approximation). In focus the result is that of the same request
+     * without the option, plus the assumption.
+     * Not combinable with `pupilSampling` or `psf`. Default off.
+     */
+    defocus?: { model: "geometric-disc" };
   };
   exposure?: {
     /** Default "manual". */
@@ -291,8 +345,12 @@ export interface SimulateCaptureOptions {
     /** 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 | CallerMaterialScene;
+  /**
+   * Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card), a declared `material-layers` scene (#491:
+   * a chart under shape-mask layers, as `resolveChartMaterialLayers` takes it; the capture is that of its `callerScene`, byte for
+   * byte, and the display view can render it on the GPU), or a caller reflectance, radiance or material function.
+   */
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -332,8 +390,8 @@ export interface SimulateCaptureOptions {
      * through `prepareRgbGamutMapping`: constant CIELAB L* and hue, chroma above 90 % of the boundary compressed.
      */
     gamutMapping?: "clip" | "perceptual";
-    /** Default: the 1.0 facade's bilinear RGGB kernels. */
-    demosaic?: SimulateCaptureDemosaic;
+    /** Default: the 1.0 facade's bilinear RGGB kernels. The record form (#395) adds a `fast` override. */
+    demosaic?: SimulateCaptureDemosaic | SimulateCaptureDemosaicRecord;
     /** Default "margin". */
     borderHandling?: SimulateCaptureBorderHandling;
     /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
@@ -391,6 +449,13 @@ export interface SimulateCaptureOptions {
      */
     pixelAperture?: SimulateCapturePixelAperture;
   };
+  /**
+   * Exact or fast (#395). `false` or omitted: every option runs its exact method, the engine reference. `true`: each option
+   * listed in {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of
+   * the exact one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option
+   * only. `diagnostics.fast` reports what was requested and what ran. No option has a fast method yet, so every result is exact.
+   */
+  fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
   /** Called after each committed RAW, development or JPEG tile. Cannot change output. */
@@ -408,10 +473,10 @@ export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png"
 
 ## SimulateCapturePixelAperture
 
-Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule.
+Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule; `fast` (#395) overrides the top-level flag.
 
 ```ts
-export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number };
+export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number; fast?: boolean };
 ```
 
 ## SimulateCaptureProgress
@@ -524,14 +589,18 @@ export interface SimulateCaptureResult {
      * `diffraction` (the object-space convolution of `lens.diffraction`; part of `raw` and `whiteBalance`), `demosaic`
      * (the AHD demosaic; part of `development`) and `encode` (PNG, JPEG or DNG serialization), with sub-millisecond
      * resolution where the host has `performance.now()`. Timings vary from run to run and never enter any digest or output byte.
+     * #492: `defocus`, the object-space convolution of `lens.defocus` out of focus (with `lens.diffraction` the combined
+     * kernel's convolution, reported here instead of under `diffraction`).
      */
-    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; demosaic?: number; encode?: number };
+    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; defocus?: number; demosaic?: number; encode?: number };
     /**
      * 2.1: the opt-in options that changed the work of this run, in a fixed order (see `SIMULATE_CAPTURE_COST_OPTIONS`).
      * Empty for a capture with every default. With `timingsMs` it lets an application measure each option's cost on
      * the user's device.
      */
     options: readonly SimulateCaptureCostOption[];
+    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
+    fast: SimulateCaptureFastReport;
   };
   provenance: {
     scientificStatus: "approximation";
@@ -559,9 +628,9 @@ frequency 1/(2·pitch)).
 
 ```ts
 export type SimulateCaptureSensorAntiAliasing =
-  | { kind: "four-spot"; separationSites?: number }
-  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
-  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+  | { kind: "four-spot"; separationSites?: number; fast?: boolean }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number; fast?: boolean }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[]; fast?: boolean };
 ```
 
 ## SimulateCaptureWhiteBalance

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

@@ -11,8 +11,38 @@ setup: use it to render one view in many regions, for example on each worker of
 
 ```ts
 export interface PreparedDisplayView {
-  /** Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. */
+  /**
+   * Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup and the
+   * realm's AHD correction states, which never change a byte (docs/DISPLAY_VIEW.md, "AHD at low signal"). With `gpu: "auto"`
+   * or `"require"` (#481) GPU renders of one prepared view run one at a time on its device, and `diagnostics.fast.execution`
+   * says whether the GPU or the CPU reference rendered the view, and why.
+   */
   render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+  /**
+   * 2.11 (#481): releases the WebGPU device the view acquired (none with `gpu: "off"`, or when `gpuDevice` gave an accelerator,
+   * whose device its owner keeps). Later renders run the CPU reference labelled `fallbackReason: "disposed"` (`"auto"`) or fail
+   * with that reason (`"require"`). Idempotent.
+   */
+  dispose(): void;
+  /**
+   * 2.10 (#447): the key of this request's AHD low-signal correction states, or null when the request has no AHD
+   * (`output.demosaic` other than "ahd"). Every input of the key is fixed when the request is prepared; two prepared views
+   * with the same key read the same states.
+   */
+  correctionKey(): string | null;
+  /**
+   * 2.10 (#447): the grid keys of every correction state a render of `view` reads (ascending, whether or not this realm holds
+   * them), found by a render of the view's region that records the states instead of computing them. No image is returned;
+   * it costs about one render whose states are all held. Fails with an InvalidConfigurationError when the request has no AHD.
+   */
+  collectCorrectionStates(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateKeys>;
+  /**
+   * 2.10 (#447): computes the correction states of `gridKeys` (from `collectCorrectionStates`, or a share of them) as a render
+   * would, stores them in this realm's cache and returns their values, for {@link bindDisplayViewCorrectionStates} in
+   * another realm. States this realm holds are read, not computed. Yields and honours `signal` like `render`. Fails with an
+   * InvalidConfigurationError when the request has no AHD or a grid key is out of range.
+   */
+  computeCorrectionStates(gridKeys: Int32Array, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateSet>;
 }
 ```
 
@@ -35,8 +65,15 @@ responses through the environment chain, the diffraction kernels, readout moment
 about 0.3–1.3 s per call on a 24 MP request; a region costs only its own pixels. Errors in the request are raised here;
 errors in the view by `render`.
 
+2.11 (#481): `prepareOptions.gpu` chooses the renderer: `"off"` (default) is the CPU reference, today's bytes; `"auto"` renders
+on WebGPU when a conforming device is available and the request is supported, else on the CPU, labelled; `"require"` fails
+instead of falling back (`ImageKernelExecutionError`, acquisition failures here, later ones from `render`). `gpuDevice` is a
+WebGPU entry point or an `ImageKernelAccelerator` whose device the view shares; without it the engine acquires one device
+for the prepared view (the request's `signal` aborts the acquisition) and `dispose()` releases it. The realm's
+`setWebGpuEnabled(false)` vetoes both GPU modes (`webgpu-disabled`). See docs/DISPLAY_VIEW.md, "Rendering on the GPU".
+
 ```ts
-export async function prepareDisplayView(options: SimulateCaptureOptions): Promise<PreparedDisplayView>;
+export async function prepareDisplayView(options: SimulateCaptureOptions, prepareOptions?: PrepareDisplayViewOptions): Promise<PreparedDisplayView>;
 ```
 
 This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

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

@@ -71,6 +71,8 @@ export interface ImageKernelAccelerator {
   readonly backend: ImageKernelBackend;
   readonly requestedBackend: ImageKernelBackend;
   readonly fallbackReason: ImageKernelFallbackReason | null;
+  /** #481: the adapter of a `webgpu-f32` accelerator's device (null for `cpu-reference`, or when the browser gives no `GPUAdapter.info`). */
+  readonly adapter: ImageKernelAdapterDescription | null;
   readonly state: ImageKernelAcceleratorState;
   renderNativeCaptureSdr(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider, options?: ImageKernelRunOptions): Promise<AcceleratedNativeCaptureSdrOutput>;
   /** Takes ownership of `input.raw` exactly like `createNativeRawDevelopmentTask` (the caller's arrays are detached). */
@@ -93,9 +95,14 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface ImageKernelAcceleratorOptions {
-  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. */
-  backend: ImageKernelBackend;
-  /** Required with `webgpu-f32`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
+  /**
+   * The one-boolean form. `true` is `backend: "webgpu-f32"` with `fallback: "cpu-reference"` unless `fallback` is given;
+   * `false` is `backend: "cpu-reference"`. Give `webgpu` or `backend`, not both.
+   */
+  webgpu?: boolean;
+  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. Required unless `webgpu` is given. */
+  backend?: ImageKernelBackend;
+  /** Required with `backend: "webgpu-f32"`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
   fallback?: "cpu-reference" | "fail";
   /** WebGPU entry point; defaults to `navigator.gpu`. Supply a worker's `navigator.gpu` explicitly if needed. */
   gpu?: unknown;

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

@@ -2,6 +2,58 @@
 
 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.
 
+## ChartCompositeProbeComponent
+
+A component of the composite chart kernel's double-float32 probe (see {@link ChartCompositeProbeRecord}). The first four are the
+outputs of the probe before 2.11.0: `two-sum` is TwoSum's low part (`s.l`), `two-product` Dekker's TwoProduct low part (`m.l`),
+`double-word-add` the double-word sum's low part (`a.l`), `double-word-multiply` the Dekker double-word product (`q.h`, `q.l`).
+
+```ts
+export type ChartCompositeProbeComponent = "two-sum" | "two-product" | "double-word-add" | "double-word-multiply" | "fma-two-product" | "fma-double-word-multiply";
+```
+
+## ChartCompositeProbeMismatch
+
+One probe output that differs from its expected value: the component, the probe input's index, and the float32 bits (hex).
+
+```ts
+export interface ChartCompositeProbeMismatch {
+  component: ChartCompositeProbeComponent;
+  input: number;
+  got: string;
+  want: string;
+}
+```
+
+## ChartCompositeProbeRecord
+
+The composite chart kernel's device probe (docs/WEBGPU.md, "Scene radiance on the GPU"): how the device evaluated the kernel's
+double-float32 building blocks, and which product path the kernel was compiled with. Diagnostic; it never changes a result.
+
+- `deviceClass`: `exact` (the written order, round to nearest); `contracted` (only the Dekker product paths differ, consistent
+  with a multiply and an add fused into one rounding); `reassociated` (a sum path differs and every differing sum low part is
+  zero, the value an algebraic simplification of (a + b) − a to b gives); `other` (anything else, such as a sum path that differs
+  with non-zero low parts, as a rounding not to nearest gives, or a non-finite output).
+- `productPath`: `dekker` when the Dekker path passes, else `fma` when the fma path passes (which needs a fused `fma`), else null
+  (the device is refused for composite charts, the 2.3 elements and material-layers scenes).
+- `fmaFused`: whether every fma TwoProduct low part was exact (a fused `fma`; WGSL also allows an unfused one).
+
+```ts
+export interface ChartCompositeProbeRecord {
+  deviceClass: "exact" | "contracted" | "reassociated" | "other";
+  productPath: "dekker" | "fma" | null;
+  fmaFused: boolean;
+  /** Probe inputs, each checked on every component. */
+  inputs: number;
+  /** Differing outputs per component. */
+  mismatchCounts: Readonly<Record<ChartCompositeProbeComponent, number>>;
+  /** The indices of the probe inputs (`PROBE_INPUTS`) whose output differs, per component. */
+  mismatchedInputs: Readonly<Record<ChartCompositeProbeComponent, readonly number[]>>;
+  /** The first differing outputs (at most eight), in component order. */
+  mismatches: readonly ChartCompositeProbeMismatch[];
+}
+```
+
 ## composeRelativeErrorBounds
 
 Composes two `relative-to-reference` bounds through a pipeline `second ∘ first`, where the second
@@ -17,6 +69,20 @@ export function composeRelativeErrorBounds(first: ImageKernelRelativeErrorBound,
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ImageKernelAdapterDescription
+
+#481: the WebGPU adapter a device came from, as `GPUAdapter.info` describes it (W3C WebGPU, `GPUAdapterInfo`): each field
+is the browser's string, or empty when the browser withholds it. Diagnostic only; it never changes a result.
+
+```ts
+export interface ImageKernelAdapterDescription {
+  vendor: string;
+  architecture: string;
+  device: string;
+  description: string;
+}
+```
+
 ## ImageKernelBackend
 
 Requested or actual execution backend.
@@ -51,6 +117,11 @@ export interface ImageKernelExecution {
   fallbackReason: ImageKernelFallbackReason | null;
   arithmetic: "float64" | "float32";
   assurance: "engine-reference" | "approximation-with-a-priori-bound";
+  /**
+   * The exact-or-fast flag in the facade's words (#395): false for `cpu-reference` (the engine reference), true for
+   * `webgpu-f32` (a bounded approximation). `backend` still names where the work ran.
+   */
+  fast: boolean;
   /**
    * True only for `cpu-reference`. Bit-exact identities (SHA-256 artifact bindings, byte-parity fixtures,
    * cross-engine determinism hashes) are CPU-only and must never be computed from a `webgpu-f32` result.
@@ -87,19 +158,20 @@ export class ImageKernelExecutionError extends Error {
 
 ## ImageKernelFailureReason
 
-Failure classes reported by {@link ImageKernelExecutionError}.
+Failure classes reported by {@link ImageKernelExecutionError}. `conformance-failed` (#481): a device failed the display view's
+run-time self-check with `gpu: "require"`.
 
 ```ts
 export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
-  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification";
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification" | "conformance-failed";
 ```
 
 ## ImageKernelFallbackReason
 
-Why a requested WebGPU backend was not used (only with `fallback: "cpu-reference"`).
+Why a requested `webgpu-f32` backend ran the CPU reference instead. `webgpu-disabled`: `setWebGpuEnabled(false)` in this realm.
 
 ```ts
-export type ImageKernelFallbackReason = "webgpu-unavailable" | "adapter-unavailable" | "device-request-failed" |
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "webgpu-disabled" | "adapter-unavailable" | "device-request-failed" |
   "insufficient-limits" | "unsupported-platform-endianness";
 ```
 

package/docs/api/gpu-webgpu-switch.md

@@ -0,0 +1,23 @@
+# gpu/webgpu-switch.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.
+
+## getWebGpuEnabled
+
+Whether this realm may use WebGPU when a caller asks for it.
+
+```ts
+export function getWebGpuEnabled(): boolean;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## setWebGpuEnabled
+
+Turns WebGPU on (`true`, the default) or off (`false`) for this realm. Anything but a boolean is refused.
+
+```ts
+export function setWebGpuEnabled(enabled: boolean): void;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.9.0",
+  "version": "2.11.1",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -88,6 +88,8 @@
     "bench:webgpu": "vitest run --config vitest.webgpu-timing.config.ts",
     "test:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs test",
     "bench:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs bench",
+    "accept:gpu": "node scripts/accept-display-view-gpu.mjs --gpu",
+    "accept:gpu:hardware": "node scripts/accept-display-view-gpu.mjs --gpu --hardware",
     "check:browser-surface": "node scripts/check-browser-surface.mjs",
     "check:licenses": "node scripts/check-license-policy.mjs",
     "check:license-headers": "node scripts/check-license-headers.mjs",