@photivra/engine 2.10.0 → 2.11.1

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.10.0",
-  "engineApiVersion": "2.10.0",
+  "packageVersion": "2.11.1",
+  "engineApiVersion": "2.11.1",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -1827,6 +1827,16 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "runtime"
     },
+    {
+      "name": "CHART_MASK_INDEX_GRAIN",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CHART_MATERIAL_LAYER_LIMITS",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "runtime"
+    },
     {
       "name": "CHART_RADIANCE_BATCH_LIMITS",
       "source": "src/facade/chart-radiance-batch.ts",
@@ -1862,6 +1872,21 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "type"
     },
+    {
+      "name": "ChartCompositeProbeComponent",
+      "source": "src/gpu/image-kernel-execution.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartCompositeProbeMismatch",
+      "source": "src/gpu/image-kernel-execution.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartCompositeProbeRecord",
+      "source": "src/gpu/image-kernel-execution.ts",
+      "kind": "type"
+    },
     {
       "name": "ChartElementScene",
       "source": "src/facade/chart-scenes.ts",
@@ -1872,6 +1897,31 @@
       "source": "src/facade/subject-framing.ts",
       "kind": "type"
     },
+    {
+      "name": "ChartMaskAnnulus",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartMaskLayer",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartMaskPolygon",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartMaskShape",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ChartMaterialLayerScene",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
     {
       "name": "ChartRadianceBatchInput",
       "source": "src/facade/chart-radiance-batch.ts",
@@ -2617,6 +2667,31 @@
       "source": "src/facade/display-view.ts",
       "kind": "type"
     },
+    {
+      "name": "DisplayViewExecution",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewFastReport",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewGpuConformance",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewGpuFallbackReason",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewGpuMode",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
     {
       "name": "DisplayViewResult",
       "source": "src/facade/simulate-capture.ts",
@@ -3467,6 +3542,11 @@
       "source": "src/optics/psf-foundation.ts",
       "kind": "runtime"
     },
+    {
+      "name": "getWebGpuEnabled",
+      "source": "src/gpu/webgpu-switch.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GlobalSensorReadoutTimingDeclaration",
       "source": "src/sensor/readout-timing.ts",
@@ -3657,6 +3737,11 @@
       "source": "src/gpu/image-kernel-accelerator.ts",
       "kind": "type"
     },
+    {
+      "name": "ImageKernelAdapterDescription",
+      "source": "src/gpu/image-kernel-execution.ts",
+      "kind": "type"
+    },
     {
       "name": "ImageKernelBackend",
       "source": "src/gpu/image-kernel-execution.ts",
@@ -5437,6 +5522,11 @@
       "source": "src/facade/simulate-display-view.ts",
       "kind": "runtime"
     },
+    {
+      "name": "PrepareDisplayViewOptions",
+      "source": "src/facade/display-view-gpu.ts",
+      "kind": "type"
+    },
     {
       "name": "PreparedRgbGamutMapping",
       "source": "src/color/gamut-mapping.ts",
@@ -6227,6 +6317,11 @@
       "source": "src/sensor/capture-mode-timing.ts",
       "kind": "type"
     },
+    {
+      "name": "resolveChartMaterialLayers",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "runtime"
+    },
     {
       "name": "resolveChartScene",
       "source": "src/facade/chart-scenes.ts",
@@ -6302,6 +6397,21 @@
       "source": "src/sensor/capture-mode-timing.ts",
       "kind": "type"
     },
+    {
+      "name": "ResolvedChartMaskLayer",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ResolvedChartMaskShape",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ResolvedChartMaterialLayers",
+      "source": "src/facade/chart-material-layers.ts",
+      "kind": "type"
+    },
     {
       "name": "ResolvedChartScene",
       "source": "src/facade/chart-scenes.ts",
@@ -7947,6 +8057,11 @@
       "source": "src/capture/focus-control.ts",
       "kind": "type"
     },
+    {
+      "name": "setWebGpuEnabled",
+      "source": "src/gpu/webgpu-switch.ts",
+      "kind": "runtime"
+    },
     {
       "name": "ShutterAngleRuleAssessment",
       "source": "src/motion/video-sequence.ts",

package/docs/api/facade-chart-material-layers.md

@@ -0,0 +1,137 @@
+# facade/chart-material-layers.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.
+
+## CHART_MASK_INDEX_GRAIN
+
+The cell index grain of every layer: cells across and down the mask box.
+
+```ts
+CHART_MASK_INDEX_GRAIN = Object.freeze({ cellsX: 64, cellsY: 16 })
+```
+
+## CHART_MATERIAL_LAYER_LIMITS
+
+Limits of a declared scene.
+
+```ts
+CHART_MATERIAL_LAYER_LIMITS = Object.freeze({ maximumLayers: 16, maximumShapes: 4096, maximumRings: 256, maximumEdges: 65_536 })
+```
+
+## ChartMaskAnnulus
+
+A stroked circle: the points at distance innerRadius ≤ d ≤ outerRadius from the centre, mask units.
+
+```ts
+export interface ChartMaskAnnulus { kind: "annulus"; centerX: number; centerY: number; innerRadius: number; outerRadius: number }
+```
+
+## ChartMaskLayer
+
+A shape mask printed over the chart: its box [0, unitsWidth] × [0, unitsHeight] (y down) fills `rectangle` (frame units, v up).
+
+```ts
+export interface ChartMaskLayer {
+  kind: "shape-mask";
+  rectangle: { u0: number; v0: number; u1: number; v1: number };
+  unitsWidth: number;
+  unitsHeight: number;
+  /** 1 to 4096 shapes, in order; the ink material where any contains the point. */
+  shapes: readonly ChartMaskShape[];
+  backgroundReflectance: ChartReflectance;
+  inkReflectance: ChartReflectance;
+}
+```
+
+## ChartMaskPolygon
+
+A filled polygon: rings as flat [x0, y0, x1, y1, …] in mask units (y down), non-zero winding over all rings.
+
+```ts
+export interface ChartMaskPolygon { kind: "polygon"; rings: readonly (readonly number[])[] }
+```
+
+## ChartMaskShape
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ChartMaskShape = ChartMaskPolygon | ChartMaskAnnulus;
+```
+
+## ChartMaterialLayerScene
+
+A chart under 1 to 16 shape-mask layers, as data; `resolveChartMaterialLayers` evaluates it.
+
+```ts
+export interface ChartMaterialLayerScene { kind: "material-layers"; sceneId: string; chart: ChartScene; layers: readonly ChartMaskLayer[] }
+```
+
+## resolveChartMaterialLayers
+
+Validates a declared material scene and resolves its chart (in a frame of `aspect` = height / width) and its
+layers. `materialAt` is the float64 reference the GPU stage is checked against, and `callerScene` is the same
+scene for `simulateCapture`'s `scene` option.
+
+```ts
+export function resolveChartMaterialLayers(input: { scene: ChartMaterialLayerScene; aspect: number }): ResolvedChartMaterialLayers;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedChartMaskLayer
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedChartMaskLayer {
+  rectangle: { u0: number; v0: number; u1: number; v1: number };
+  unitsWidth: number;
+  unitsHeight: number;
+  /** Mask units per frame unit: unitsWidth / (u1 − u0) and unitsHeight / (v1 − v0). */
+  scaleX: number;
+  scaleY: number;
+  shapes: readonly ResolvedChartMaskShape[];
+  cellsX: number;
+  cellsY: number;
+  cellWidth: number;
+  cellHeight: number;
+  /** Per cell (row by row), the shape indices whose bounding box meets the cell grown by one cell. */
+  cells: readonly Uint32Array[];
+  backgroundMaterial: number;
+  inkMaterial: number;
+  /** Whether a point in mask units is ink (through the cell index). */
+  containsUnits(x: number, y: number): boolean;
+}
+```
+
+## ResolvedChartMaskShape
+
+Internal: a shape with its bounding box and flattened edges (polygon) or squared radii (annulus).
+
+```ts
+export type ResolvedChartMaskShape =
+  | { kind: "polygon"; box: readonly [number, number, number, number]; edges: Float64Array }
+  | { kind: "annulus"; box: readonly [number, number, number, number]; centerX: number; centerY: number; inner2: number; outer2: number };
+```
+
+## ResolvedChartMaterialLayers
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedChartMaterialLayers {
+  kind: "material-layers";
+  sceneId: string;
+  /** The chart under the layers; its materials come first in `materials`. */
+  chart: ResolvedChartScene;
+  layers: readonly ResolvedChartMaskLayer[];
+  materials: ResolvedChartScene["materials"];
+  /** Internal: the caller input behind each material (undefined for an engine neutral), for the scene digest. */
+  materialInputs: readonly unknown[];
+  /** Material index at a frame point (u right, v up): the topmost layer whose rectangle holds the point, else the chart. */
+  materialAt(u: number, v: number): number;
+  /** The same scene as a caller material scene for `simulateCapture` and the display view (chart-local coordinates when the chart has a size). */
+  callerScene: CallerMaterialScene;
+}
+```

package/docs/api/facade-chart-radiance-batch.md

@@ -46,8 +46,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface ChartRadianceBatchInput {
   schemaVersion: typeof CHART_RADIANCE_BATCH_SCHEMA_VERSION;
-  /** An engine chart preset (caller scene functions are not supported here). */
-  scene: ChartScene;
+  /** An engine chart preset, or (#477) a declared `material-layers` scene: a chart under shape-mask layers. Caller scene functions are not supported here. */
+  scene: ChartScene | ChartMaterialLayerScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   /** Frame height / width. */
@@ -74,7 +74,12 @@ Validated plan with the resolved chart, illuminant and irradiance scale. Arrays
 
 ```ts
 export interface ChartRadianceBatchPlan {
+  /** The resolved chart; with a `material-layers` scene, the chart under the layers. */
   chart: ResolvedChartScene;
+  /** The resolved layers of a `material-layers` scene, or null for a chart preset. */
+  layers: ResolvedChartMaterialLayers | null;
+  /** Every material a query can resolve to: the chart's, then each layer's background and ink. */
+  materials: ResolvedChartScene["materials"];
   illuminant: ResolvedCaptureIlluminant;
   irradianceScale: number;
   queryCount: number;

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

@@ -0,0 +1,94 @@
+# facade/display-view-gpu.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.
+
+## DisplayViewExecution
+
+2.11 (#481): where a display view's render ran, in the words of the image-kernel execution record (`ImageKernelExecution`):
+`backend` names the path that ran (`cpu-reference`, the float64 engine reference, or `webgpu-f32`, a float32 approximation
+within `errorBound`), `requestedBackend` what `gpu` asked for, and `fallbackReason` why a request for the GPU ran the CPU.
+`adapter` describes the device's adapter whenever one was involved, also when the view then fell back; `conformance` is
+the device's self-check once it has run. A CPU render keeps `assurance: "engine-reference"` and `fast: false`.
+
+```ts
+export interface DisplayViewExecution extends Omit<ImageKernelExecution, "fallbackReason"> {
+  /** The `gpu` option the view was prepared with. */
+  gpu: DisplayViewGpuMode;
+  fallbackReason: DisplayViewGpuFallbackReason | null;
+  adapter: ImageKernelAdapterDescription | null;
+  conformance: DisplayViewGpuConformance | null;
+  /**
+   * 2.11: the composite chart kernel's device probe when this render needed it (composite charts, the 2.3 elements and
+   * `material-layers` scenes): the device class and the product path the kernel ran with, or, on a refusal (`fallbackReason`
+   * `unsupported-on-backend`), why. Null when the render did not run the probe (the 2.0 presets, `gpu: "off"`).
+   */
+  compositeProbe: ChartCompositeProbeRecord | null;
+}
+```
+
+## DisplayViewFastReport
+
+2.11 (#481): `diagnostics.fast` of a display view: the capture's report plus where the render ran.
+
+```ts
+export interface DisplayViewFastReport extends SimulateCaptureFastReport {
+  /** Where this render ran (see {@link DisplayViewExecution}). `assurance` above follows it. */
+  execution: DisplayViewExecution;
+}
+```
+
+## DisplayViewGpuConformance
+
+2.11 (#481): the run-time conformance self-check of a device, run once before the view's first GPU render.
+
+```ts
+export interface DisplayViewGpuConformance {
+  /** The ids of the cases run, in order (the built-in image-kernel cases, then the renderer's own). */
+  cases: readonly string[];
+  passed: boolean;
+  /** The first case that failed, or null. */
+  failedCase: string | null;
+  /** What the failed case reported, or null. */
+  detail: string | null;
+}
+```
+
+## DisplayViewGpuFallbackReason
+
+2.11 (#481): why a display view that asked for the GPU (`gpu: "auto"`) ran the CPU reference. The accelerator's acquisition
+reasons, plus: `unsupported-on-backend` (no GPU display-view renderer exists in this version, or it does not support the
+request), `conformance-failed` (the device failed the run-time self-check before the view's first GPU render), `device-lost`
+(the device was lost; the rest of the view runs on the CPU) and `disposed` (the prepared view was disposed).
+
+```ts
+export type DisplayViewGpuFallbackReason = ImageKernelFallbackReason | "unsupported-on-backend" | "conformance-failed" | "device-lost" | "disposed";
+```
+
+## DisplayViewGpuMode
+
+2.11 (#481): whether a prepared display view may render on the GPU. `"off"` (the default) is the CPU reference, today's
+behaviour byte for byte. `"auto"` renders on WebGPU when a conforming device is available and the request is supported, and
+otherwise runs the CPU reference and says why. `"require"` fails instead of falling back. In the accelerator's words: `"auto"`
+is `backend: "webgpu-f32"` with `fallback: "cpu-reference"`, `"require"` is `fallback: "fail"`, `"off"` is `backend: "cpu-reference"`.
+
+```ts
+export type DisplayViewGpuMode = "off" | "auto" | "require";
+```
+
+## PrepareDisplayViewOptions
+
+2.11 (#481): the second argument of `prepareDisplayView`.
+
+```ts
+export interface PrepareDisplayViewOptions {
+  /** See {@link DisplayViewGpuMode}. Default `"off"`. */
+  gpu?: DisplayViewGpuMode;
+  /**
+   * Where the device comes from, with `gpu: "auto"` or `"require"`: a WebGPU entry point (a worker's `navigator.gpu`), or an
+   * `ImageKernelAccelerator` whose device the view shares (the accelerator keeps ownership; `dispose()` of the prepared view
+   * leaves it alone). Without it the engine acquires a device from `globalThis.navigator.gpu` and owns it until `dispose()`.
+   * Refused with `gpu: "off"`.
+   */
+  gpuDevice?: unknown;
+}
+```

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

@@ -31,8 +31,8 @@ export interface DisplayViewResult {
    */
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
     timingsMs: { view: number; total: number };
-    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
-    fast: SimulateCaptureFastReport };
+    /** #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`. */
@@ -96,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)
 ```
@@ -323,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". */
@@ -334,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;
   /**
@@ -574,8 +589,10 @@ 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

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

@@ -13,9 +13,17 @@ setup: use it to render one view in many regions, for example on each worker of
 export interface PreparedDisplayView {
   /**
    * 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").
+   * 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
@@ -57,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;