@photivra/engine 2.10.0 → 2.11.1

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.
@@ -92,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.10.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",