@photivra/engine 2.9.0 → 2.11.1

package/docs/USAGE.md

@@ -1552,6 +1552,8 @@ console.log(components.value.composition.status); // "not-composed"
 
 The foundation deliberately **does not combine** geometric defocus and circular diffraction into a synthetic PSF, MTF, convolution kernel, combined blur radius or "lens sharpness" score.
 
+This foundation API is separate from the capture facade. With `lens.defocus` and `lens.diffraction` together, `simulateCapture` convolves each spectral node's diffraction kernel with the geometric defocus disc (#492). That is a labelled approximation, and it has its own `lens.defocus` assumption. See [Optics](QUICK_START.md#optics).
+
 It already records field position, even though the current defocus and Airy diagnostics do not vary across the field. Future field-curvature, pupil-clipping, bokeh and aberration contributions can then use the same context without reinterpreting existing outputs.
 
 The spectral basis is explicitly monochromatic (one wavelength) for the Airy diagnostic. This does not create a spectral lens or sensor-colour model.
@@ -7300,18 +7302,19 @@ console.log(merged.raw.codes.length, merged.providerEvaluationCount);
 - By default they run on the float64 CPU reference.
 - If you opt in, they run on the `webgpu-f32` backend (WebGPU, 32-bit floats).
 - Every result's `execution` label names the backend that actually ran, any reason for falling back, and the error bound against the reference, stated in advance.
+- One boolean chooses: `{ webgpu: true }` asks for the GPU and runs the reference if it is missing; `{ webgpu: false }` is the reference. `setWebGpuEnabled(false)` turns the GPU off for the whole realm, whatever callers ask, and labels those results `webgpu-disabled`.
 
 See [WebGPU backend](https://github.com/Photivra/photivra/blob/main/docs/WEBGPU.md) for the bounds, the supported domain and the browser test.
 
 ```ts
-import { createImageKernelAccelerator, calculateIrradianceConvolution } from "@photivra/engine";
+import { createImageKernelAccelerator, calculateIrradianceConvolution, getWebGpuEnabled, setWebGpuEnabled } from "@photivra/engine";
 
 const width = 16, height = 8, kernelRadius = 1;
 const input = { schemaVersion: "0.1.0" as const, width, height, kernelRadius, patchWidth: width, patchHeight: height,
   boundary: "zero-outside-grid" as const, samples: new Float64Array(width * height).fill(2),
   kernels: Float64Array.from([0, .1, 0, .1, .6, .1, 0, .1, 0]) };
 
-const accelerator = await createImageKernelAccelerator({ backend: "webgpu-f32", fallback: "cpu-reference" });
+const accelerator = await createImageKernelAccelerator({ webgpu: true }); // the same as { backend: "webgpu-f32", fallback: "cpu-reference" }
 const result = await accelerator.convolveIrradiance(input);
 // Without WebGPU (e.g. Node) this ran the reference and says so.
 console.log(result.execution.backend, result.execution.fallbackReason, result.execution.bitIdenticalToReference);
@@ -7319,6 +7322,13 @@ console.log(result.execution.backend, result.execution.fallbackReason, result.ex
 const reference = calculateIrradianceConvolution(input).values;
 console.log(result.execution.backend === "cpu-reference" ? result.values.every((v, i) => v === reference[i]) : result.execution.errorBound);
 accelerator.dispose();
+
+// The realm's switch: off, every request for the GPU runs the reference and says why.
+setWebGpuEnabled(false);
+const cpuOnly = await createImageKernelAccelerator({ webgpu: true });
+console.log(cpuOnly.backend, cpuOnly.fallbackReason, getWebGpuEnabled()); // "cpu-reference" "webgpu-disabled" false
+cpuOnly.dispose();
+setWebGpuEnabled(true);
 ```
 
 Two image-formation stages use the same accelerator:
@@ -7516,6 +7526,57 @@ const view = await simulateDisplayView({ scene: { preset: "slanted-edge" }, sens
 console.log(view.kind, view.view.scaleX, view.assumptions.find((a) => a.id === "view.definition")?.value);
 ```
 
+#### Rendering a prepared view on the GPU (2.11, #481)
+
+`prepareDisplayView(request, { gpu })` chooses the renderer: `"off"` (the default) is the CPU reference, `"auto"` the GPU
+when a conforming device is available and the request is supported (else the CPU, labelled), `"require"` fails instead of
+falling back. `gpuDevice` hands the view a worker's `navigator.gpu` or an `ImageKernelAccelerator` whose device it shares.
+Every render says which path ran in `diagnostics.fast.execution`, in the accelerator's words. No GPU display-view renderer
+exists yet (#478), so today `"auto"` runs the CPU reference labelled `unsupported-on-backend` without requesting a device;
+see [Rendering on the GPU](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#rendering-on-the-gpu).
+
+```ts
+import { prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
+
+const request: SimulateCaptureOptions = { scene: { preset: "siemens-star" }, sensor: { pixelPitchMicrometers: 4 }, output: { width: 600, height: 400 } };
+const prepared = await prepareDisplayView(request, { gpu: "auto" }); // acquisition failures fall back; with "require" they throw here
+const tile = await prepared.render({ width: 300, height: 200, region: { x: 120, y: 80, width: 32, height: 32 } });
+const ran = tile.diagnostics.fast.execution;
+// "cpu-reference" when the reference ran (and why), "webgpu-f32" with its bound and adapter when the GPU did.
+console.log(ran.backend, ran.fallbackReason, ran.assurance, ran.errorBound, ran.adapter, tile.diagnostics.fast.assurance);
+prepared.dispose(); // releases a device the view acquired; a shared accelerator's device stays its owner's
+```
+
+#### Sharing AHD correction states between workers
+
+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])`.
+
+```ts
+import { serializeDisplayViewCorrectionStates, bindDisplayViewCorrectionStates, prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
+
+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));
+```
+
 ### Facade 2.0 options: output, demosaic, optics and motion
 
 Each 2.0 option is opt-in and uses an existing public contract. Without them, the facade's output is
@@ -7562,6 +7623,25 @@ const barrel = await simulateCapture({
 console.log(barrel.request.siteInput(0).environment.lensFieldMapping?.distortion.kind);
 ```
 
+`lens.defocus: { model: "geometric-disc" }` (#492) renders defocus of the flat scene plane when
+`lens.focusDistanceM` differs from `subjectDistanceM`. The thin-lens blur circle becomes a uniform disc on the site
+lattice, and the capture convolves the scene radiance with it, which is a geometric approximation. With
+`lens.diffraction`, each spectral node's diffraction kernel is convolved with the disc, which is a further
+approximation. The `lens.defocus` assumption records the diameter in µm and in sites, the kernel radius and the
+execution. `simulateDisplayView` does not render it yet. See [Optics](QUICK_START.md#optics).
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const blurred = await simulateCapture({
+  scene: { preset: "slanted-edge" },
+  subjectDistanceM: 2,
+  lens: { focalLengthMm: 50, fNumber: 4, focusDistanceM: 1.8, defocus: { model: "geometric-disc" } },
+  output: { width: 16, height: 12 }
+});
+console.log(blurred.assumptions.find((a) => a.id === "lens.defocus")?.value); // diameterSites ≈ 5.95, kernelRadiusSites 3
+```
+
 `motion.angularVelocityRadPerSec` rotates the camera during the exposure (8 time midpoints by
 default). `motion.shutter: "rolling"` derives each site's exposure window from the body's rolling
 readout, with `resolveElectronicRollingShutterExposureSchedule`. See [Motion](QUICK_START.md#motion).

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.9.0" as const
+ENGINE_API_VERSION = "2.11.1" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.9.0",
-  "engineApiVersion": "2.9.0",
+  "packageVersion": "2.11.1",
+  "engineApiVersion": "2.11.1",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -212,6 +212,11 @@
       "source": "src/processing/denoise.ts",
       "kind": "type"
     },
+    {
+      "name": "bindDisplayViewCorrectionStates",
+      "source": "src/facade/display-view.ts",
+      "kind": "runtime"
+    },
     {
       "name": "bindIsoCapabilityToExposureCapabilities",
       "source": "src/equipment/iso-capabilities.ts",
@@ -1822,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",
@@ -1857,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",
@@ -1867,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",
@@ -2602,6 +2657,41 @@
       "source": "src/core/spectral-composition.ts",
       "kind": "type"
     },
+    {
+      "name": "DisplayViewCorrectionStateKeys",
+      "source": "src/facade/display-view.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DisplayViewCorrectionStateSet",
+      "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",
@@ -3452,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",
@@ -3642,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",
@@ -5422,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",
@@ -6212,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",
@@ -6287,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",
@@ -7867,6 +7992,11 @@
       "source": "src/sensor/dark-current.ts",
       "kind": "type"
     },
+    {
+      "name": "serializeDisplayViewCorrectionStates",
+      "source": "src/facade/display-view.ts",
+      "kind": "runtime"
+    },
     {
       "name": "serializeNativeRawDng",
       "source": "src/capture/native-raw-dng.ts",
@@ -7927,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",
@@ -7972,6 +8107,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SIMULATE_CAPTURE_FAST_OPTIONS",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS",
       "source": "src/facade/simulate-capture.ts",
@@ -8007,6 +8147,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureDemosaicRecord",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureDngPart",
       "source": "src/facade/simulate-capture.ts",
@@ -8017,6 +8162,16 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureFastOption",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureFastReport",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureLensDistortion",
       "source": "src/facade/simulate-capture.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;
+}
+```