@aura3d/rendering 1.4.0 → 1.4.2

package/src/RendererVisualPipelineReport.ts

@@ -1,836 +0,0 @@
-import {
-  createExternalParityColorManagementPolicy,
-  type A3DColorManagementPolicy,
-  type A3DColorSpace,
-  type A3DTextureSemantic
-} from "./ColorManagement";
-import {
-  createToneMappingCalibration,
-  type BloomOptions,
-  type ChromaticAberrationOptions,
-  type ColorGradeOptions,
-  type ContactShadowPostProcessOptions,
-  type DepthOfFieldOptions,
-  type FXAAOptions,
-  type FilmGrainOptions,
-  type MotionBlurOptions,
-  type OutlineOptions,
-  type PostProcessColorSpace,
-  type SSAOOptions,
-  type SSROptions,
-  type TAAOptions,
-  type ToneMappingCalibration,
-  type ToneMappingOperator,
-  type ToneMappingOptions,
-  type ToneMappingPresetName
-} from "./PostProcessPass";
-import {
-  createRendererPostprocessPlanDiagnostics,
-  type RendererPostprocessExecutionMode,
-  type RendererPostprocessPlanDiagnostics
-} from "./RendererPostprocessPlan";
-import { listExternalParityToneMappingPresets } from "./ToneMapping";
-import type {
-  RenderDevice,
-  RenderDeviceCapability,
-  RenderDeviceDiagnostics,
-  RenderTargetDescriptor
-} from "./RenderDevice";
-
-export type RendererVisualPipelineStatus = "supported" | "partial" | "unsupported";
-export type RendererVisualTargetFormat = Extract<RenderTargetDescriptor["format"], "rgba8" | "rgba16f" | "rgba32f">;
-export type RendererVisualPostprocessPassName =
-  | "tone-mapping"
-  | "color-grade"
-  | "bloom"
-  | "chromatic-aberration"
-  | "film-grain"
-  | "depth-of-field"
-  | "motion-blur"
-  | "contact-shadow"
-  | "ssao"
-  | "ssr"
-  | "taa"
-  | "outline"
-  | "fxaa";
-
-export type RendererUnsupportedVisualCapability =
-  | "display-p3-output"
-  | "rec2020-output"
-  | "hdr-display-swapchain"
-  | "automatic-png-color-profile";
-
-export interface RendererVisualPostprocessDescriptor {
-  readonly targetFormat?: RendererVisualTargetFormat;
-  readonly toneMapping?: ToneMappingOptions | false;
-  readonly colorGrade?: ColorGradeOptions | boolean;
-  readonly bloom?: BloomOptions | boolean;
-  readonly chromaticAberration?: ChromaticAberrationOptions | boolean;
-  readonly filmGrain?: FilmGrainOptions | boolean;
-  readonly depthOfField?: DepthOfFieldOptions | false;
-  readonly motionBlur?: MotionBlurOptions | false;
-  readonly contactShadow?: ContactShadowPostProcessOptions | false;
-  readonly ssao?: SSAOOptions | false;
-  readonly ssr?: SSROptions | false;
-  readonly taa?: TAAOptions | false;
-  readonly outline?: OutlineOptions | boolean;
-  readonly fxaa?: FXAAOptions | boolean;
-}
-
-export interface RendererCanvasBackingInput {
-  readonly cssWidth: number;
-  readonly cssHeight: number;
-  readonly devicePixelRatio: number;
-  readonly actualWidth?: number;
-  readonly actualHeight?: number;
-}
-
-export interface RendererCanvasBackingReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly cssWidth: number;
-  readonly cssHeight: number;
-  readonly devicePixelRatio: number;
-  readonly expectedWidth: number;
-  readonly expectedHeight: number;
-  readonly actualWidth?: number;
-  readonly actualHeight?: number;
-  readonly effectiveDevicePixelRatio?: number;
-  readonly backingStoreMatchesDisplay: boolean;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererScreenshotConsistencyInput {
-  readonly width: number;
-  readonly height: number;
-  readonly byteLength: number;
-  readonly expectedWidth: number;
-  readonly expectedHeight: number;
-  readonly expectedByteLength?: number;
-  readonly colorSpace?: A3DColorSpace;
-}
-
-export interface RendererScreenshotConsistencyReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly width: number;
-  readonly height: number;
-  readonly byteLength: number;
-  readonly expectedWidth: number;
-  readonly expectedHeight: number;
-  readonly expectedByteLength: number;
-  readonly colorSpace: A3DColorSpace;
-  readonly pixelFormat: "rgba8";
-  readonly readbackMatchesBackingStore: boolean;
-  readonly colorProfileEmbedded: false;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererCaptureQualityInput {
-  readonly cssWidth: number;
-  readonly cssHeight: number;
-  readonly backingWidth: number;
-  readonly backingHeight: number;
-  readonly screenshotWidth: number;
-  readonly screenshotHeight: number;
-  readonly captureCssWidth?: number;
-  readonly captureCssHeight?: number;
-  readonly devicePixelRatio?: number;
-  readonly minimumEffectiveDpr?: number;
-  readonly label?: string;
-}
-
-export interface RendererCaptureQualityReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly label?: string;
-  readonly cssWidth: number;
-  readonly cssHeight: number;
-  readonly backingWidth: number;
-  readonly backingHeight: number;
-  readonly screenshotWidth: number;
-  readonly screenshotHeight: number;
-  readonly captureCssWidth: number;
-  readonly captureCssHeight: number;
-  readonly devicePixelRatio?: number;
-  readonly minimumEffectiveDpr: number;
-  readonly effectiveBackingDprX: number;
-  readonly effectiveBackingDprY: number;
-  readonly effectiveCaptureDprX: number;
-  readonly effectiveCaptureDprY: number;
-  readonly captureToBackingScaleX: number;
-  readonly captureToBackingScaleY: number;
-  readonly capturesFullCanvas: boolean;
-  readonly fullCanvasPixelMatch: boolean;
-  readonly captureDownsamplesCanvas: boolean;
-  readonly captureUpscalesCanvas: boolean;
-  readonly meetsMinimumEffectiveDpr: boolean;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererFrameCadenceInput {
-  readonly targetFrameMs?: number;
-  readonly renderMs?: number;
-  readonly loopMs?: number;
-  readonly frameIntervalMs?: number;
-  readonly readbackMs?: number;
-  readonly screenshotCaptureOverheadMs?: number;
-  readonly sampleCount?: number;
-}
-
-export interface RendererFrameCadenceReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly targetFrameMs: number;
-  readonly renderMs?: number;
-  readonly loopMs?: number;
-  readonly frameIntervalMs?: number;
-  readonly readbackMs?: number;
-  readonly screenshotCaptureOverheadMs?: number;
-  readonly sampleCount?: number;
-  readonly renderBudgetRatio?: number;
-  readonly loopBudgetRatio?: number;
-  readonly frameIntervalBudgetRatio?: number;
-  readonly readbackBudgetRatio?: number;
-  readonly captureOverheadFrames?: number;
-  readonly loopHeadroomMs?: number;
-  readonly stableForCapture: boolean;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererVisualPipelineReportOptions {
-  readonly device: RenderDevice;
-  readonly width: number;
-  readonly height: number;
-  readonly postprocess?: RendererVisualPostprocessDescriptor | boolean;
-  readonly colorManagement?: A3DColorManagementPolicy;
-  readonly canvas?: RendererCanvasBackingInput;
-  readonly screenshot?: Omit<RendererScreenshotConsistencyInput, "expectedWidth" | "expectedHeight" | "colorSpace"> & {
-    readonly colorSpace?: A3DColorSpace;
-  };
-  readonly capture?: RendererCaptureQualityInput;
-  readonly frameCadence?: RendererFrameCadenceInput;
-  readonly diagnostics?: RenderDeviceDiagnostics;
-}
-
-export interface RendererVisualColorReport {
-  readonly lightingColorSpace: "linear";
-  readonly outputColorSpace: A3DColorSpace;
-  readonly supportedOutputColorSpaces: readonly A3DColorSpace[];
-  readonly unsupportedOutputColorSpaces: readonly ["display-p3", "rec2020"];
-  readonly texturePolicy: Readonly<Record<A3DTextureSemantic, A3DColorSpace>>;
-  readonly ldrFallbackAllowed: boolean;
-  readonly fallbackBehavior: string;
-}
-
-export interface RendererVisualToneMappingReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly enabled: boolean;
-  readonly operator?: ToneMappingOperator;
-  readonly exposure?: number;
-  readonly whitePoint?: number;
-  readonly gamma?: number;
-  readonly inputColorSpace?: PostProcessColorSpace;
-  readonly outputColorSpace?: PostProcessColorSpace;
-  readonly calibration?: ToneMappingCalibration;
-  readonly availablePresets: readonly ToneMappingPresetName[];
-  readonly warnings: readonly string[];
-}
-
-export interface RendererVisualPostprocessReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly enabled: boolean;
-  readonly passNames: readonly RendererVisualPostprocessPassName[];
-  readonly targetFormat: RendererVisualTargetFormat;
-  readonly sourceTargetFormat: RendererVisualTargetFormat;
-  readonly executionMode: RendererPostprocessExecutionMode;
-  readonly nativePresentation: boolean;
-  readonly usesReadback: boolean;
-  readonly missingInputs: readonly string[];
-  readonly readbackPassNames: readonly RendererVisualPostprocessPassName[];
-  readonly rendererOwnedPassNames: readonly RendererVisualPostprocessPassName[];
-  readonly clarityWarnings: readonly string[];
-  readonly forwardOutputColorSpace: PostProcessColorSpace;
-  readonly presentationColorSpace: A3DColorSpace;
-  readonly renderTargetWidth: number;
-  readonly renderTargetHeight: number;
-  readonly plan?: RendererPostprocessPlanDiagnostics;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererVisualHdrTargetReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly requested: boolean;
-  readonly supportedByBackend: boolean;
-  readonly capabilityAdvertised: boolean;
-  readonly targetFormat: RendererVisualTargetFormat;
-  readonly fallbackFormat?: "rgba8";
-  readonly toneMappingRequired: boolean;
-  readonly warnings: readonly string[];
-}
-
-export interface RendererVisualPipelineReport {
-  readonly status: RendererVisualPipelineStatus;
-  readonly backend: RenderDevice["kind"];
-  readonly renderer: string;
-  readonly width: number;
-  readonly height: number;
-  readonly capabilities: readonly RenderDeviceCapability[];
-  readonly color: RendererVisualColorReport;
-  readonly toneMapping: RendererVisualToneMappingReport;
-  readonly hdrTarget: RendererVisualHdrTargetReport;
-  readonly postprocess: RendererVisualPostprocessReport;
-  readonly canvas?: RendererCanvasBackingReport;
-  readonly screenshot?: RendererScreenshotConsistencyReport;
-  readonly capture?: RendererCaptureQualityReport;
-  readonly frameCadence?: RendererFrameCadenceReport;
-  readonly diagnostics?: RenderDeviceDiagnostics;
-  readonly unsupportedCapabilities: Readonly<Record<RendererUnsupportedVisualCapability, string>>;
-  readonly warnings: readonly string[];
-}
-
-const SUPPORTED_OUTPUT_COLOR_SPACES: readonly A3DColorSpace[] = ["linear", "srgb"];
-const UNSUPPORTED_OUTPUT_COLOR_SPACES = ["display-p3", "rec2020"] as const;
-const HDR_FORMATS: readonly RendererVisualTargetFormat[] = ["rgba16f", "rgba32f"];
-
-const UNSUPPORTED_CAPABILITIES: Readonly<Record<RendererUnsupportedVisualCapability, string>> = {
-  "display-p3-output": "Renderer output color space is limited to linear or sRGB; display-p3 output is not exposed.",
-  "rec2020-output": "Renderer output color space is limited to linear or sRGB; Rec.2020 output is not exposed.",
-  "hdr-display-swapchain": "HDR render targets can be tone-mapped, but HDR display swapchain output is not exposed.",
-  "automatic-png-color-profile": "Screenshot readback is RGBA8 bytes; PNG/ICC profile tagging is owned by the caller."
-};
-
-export function createRendererVisualPipelineReport(
-  options: RendererVisualPipelineReportOptions
-): RendererVisualPipelineReport {
-  assertPositiveInteger(options.width, "width");
-  assertPositiveInteger(options.height, "height");
-
-  const capabilities = [...(options.device.info.capabilities ?? [])];
-  const capabilitySet = new Set<RenderDeviceCapability>(capabilities);
-  const colorManagement = options.colorManagement ?? createExternalParityColorManagementPolicy();
-  const postprocess = normalizePostprocess(options.postprocess);
-  const postprocessEnabled = postprocess !== undefined;
-  const passNames = postprocess ? collectPostprocessPassNames(postprocess) : [];
-  const targetFormat = postprocess ? resolvePostprocessTargetFormat(capabilitySet, postprocess) : "rgba8";
-  const postprocessPlan = postprocess
-    ? createRendererPostprocessPlanDiagnostics(postprocess, {
-        sourceTargetFormat: targetFormat,
-        targetFormat,
-        nativeLdrPostprocess: Boolean(options.device.presentLdrPostprocess),
-        rendererDepthAvailable: capabilitySet.has("depth-textures")
-      })
-    : undefined;
-  const hdrTarget = createHdrTargetReport(capabilitySet, targetFormat, postprocess?.toneMapping);
-  const toneMapping = createToneMappingReport(postprocess, targetFormat);
-  const postprocessReport = createPostprocessReport({
-    enabled: postprocessEnabled,
-    passNames,
-    targetFormat,
-    plan: postprocessPlan,
-    width: options.width,
-    height: options.height,
-    presentationColorSpace: colorManagement.outputColorSpace,
-    hdrTargetStatus: hdrTarget.status,
-    toneMappingStatus: toneMapping.status
-  });
-  const canvas = options.canvas ? evaluateRendererCanvasBacking(options.canvas) : undefined;
-  const screenshot = options.screenshot
-    ? evaluateRendererScreenshotConsistency({
-        ...options.screenshot,
-        expectedWidth: options.width,
-        expectedHeight: options.height,
-        colorSpace: options.screenshot.colorSpace ?? colorManagement.outputColorSpace
-      })
-    : undefined;
-  const capture = options.capture ? evaluateRendererCaptureQuality(options.capture) : undefined;
-  const frameCadence = options.frameCadence ? evaluateRendererFrameCadence(options.frameCadence) : undefined;
-  const warnings = [
-    ...hdrTarget.warnings,
-    ...toneMapping.warnings,
-    ...postprocessReport.warnings,
-    ...(canvas?.warnings ?? []),
-    ...(screenshot?.warnings ?? []),
-    ...(capture?.warnings ?? []),
-    ...(frameCadence?.warnings ?? [])
-  ];
-
-  return {
-    status: combineStatuses([
-      hdrTarget.status,
-      toneMapping.status,
-      postprocessReport.status,
-      canvas?.status,
-      screenshot?.status,
-      capture?.status,
-      frameCadence?.status
-    ]),
-    backend: options.device.kind,
-    renderer: options.device.info.renderer,
-    width: options.width,
-    height: options.height,
-    capabilities,
-    color: {
-      lightingColorSpace: colorManagement.lightingColorSpace,
-      outputColorSpace: colorManagement.outputColorSpace,
-      supportedOutputColorSpaces: SUPPORTED_OUTPUT_COLOR_SPACES,
-      unsupportedOutputColorSpaces: UNSUPPORTED_OUTPUT_COLOR_SPACES,
-      texturePolicy: colorManagement.texturePolicy,
-      ldrFallbackAllowed: colorManagement.allowLdrFallback,
-      fallbackBehavior: colorManagement.fallbackBehavior
-    },
-    toneMapping,
-    hdrTarget,
-    postprocess: postprocessReport,
-    ...(canvas ? { canvas } : {}),
-    ...(screenshot ? { screenshot } : {}),
-    ...(capture ? { capture } : {}),
-    ...(frameCadence ? { frameCadence } : {}),
-    ...(options.diagnostics ? { diagnostics: options.diagnostics } : {}),
-    unsupportedCapabilities: UNSUPPORTED_CAPABILITIES,
-    warnings
-  };
-}
-
-export function evaluateRendererCanvasBacking(input: RendererCanvasBackingInput): RendererCanvasBackingReport {
-  assertPositiveFinite(input.cssWidth, "cssWidth");
-  assertPositiveFinite(input.cssHeight, "cssHeight");
-  assertPositiveFinite(input.devicePixelRatio, "devicePixelRatio");
-  const expectedWidth = Math.max(1, Math.round(input.cssWidth * input.devicePixelRatio));
-  const expectedHeight = Math.max(1, Math.round(input.cssHeight * input.devicePixelRatio));
-  const hasActualDimensions = input.actualWidth !== undefined && input.actualHeight !== undefined;
-  const matches = hasActualDimensions
-    ? input.actualWidth === expectedWidth && input.actualHeight === expectedHeight
-    : false;
-  const warnings = createCanvasBackingWarnings(input, expectedWidth, expectedHeight, hasActualDimensions, matches);
-
-  return {
-    status: matches ? "supported" : "partial",
-    cssWidth: input.cssWidth,
-    cssHeight: input.cssHeight,
-    devicePixelRatio: input.devicePixelRatio,
-    expectedWidth,
-    expectedHeight,
-    ...(input.actualWidth !== undefined ? { actualWidth: input.actualWidth } : {}),
-    ...(input.actualHeight !== undefined ? { actualHeight: input.actualHeight } : {}),
-    ...(hasActualDimensions ? { effectiveDevicePixelRatio: round(input.actualWidth! / input.cssWidth) } : {}),
-    backingStoreMatchesDisplay: matches,
-    warnings
-  };
-}
-
-export function evaluateRendererScreenshotConsistency(
-  input: RendererScreenshotConsistencyInput
-): RendererScreenshotConsistencyReport {
-  assertPositiveInteger(input.width, "width");
-  assertPositiveInteger(input.height, "height");
-  assertPositiveInteger(input.expectedWidth, "expectedWidth");
-  assertPositiveInteger(input.expectedHeight, "expectedHeight");
-  assertPositiveInteger(input.byteLength, "byteLength");
-  if (input.expectedByteLength !== undefined) assertPositiveInteger(input.expectedByteLength, "expectedByteLength");
-  const expectedByteLength = input.expectedByteLength ?? input.expectedWidth * input.expectedHeight * 4;
-  const dimensionsMatch = input.width === input.expectedWidth && input.height === input.expectedHeight;
-  const bytesMatch = input.byteLength === expectedByteLength;
-  const warnings: string[] = [];
-  if (!dimensionsMatch) {
-    warnings.push(`Screenshot readback ${input.width}x${input.height} does not match renderer backing store ${input.expectedWidth}x${input.expectedHeight}.`);
-  }
-  if (!bytesMatch) {
-    warnings.push(`Screenshot byte length ${input.byteLength} does not match expected RGBA8 byte length ${expectedByteLength}.`);
-  }
-  warnings.push("Screenshot readback reports RGBA8 pixels; embedded PNG/ICC color profiles are not guaranteed by the renderer.");
-
-  return {
-    status: dimensionsMatch && bytesMatch ? "supported" : "partial",
-    width: input.width,
-    height: input.height,
-    byteLength: input.byteLength,
-    expectedWidth: input.expectedWidth,
-    expectedHeight: input.expectedHeight,
-    expectedByteLength,
-    colorSpace: input.colorSpace ?? "srgb",
-    pixelFormat: "rgba8",
-    readbackMatchesBackingStore: dimensionsMatch && bytesMatch,
-    colorProfileEmbedded: false,
-    warnings
-  };
-}
-
-export function evaluateRendererCaptureQuality(input: RendererCaptureQualityInput): RendererCaptureQualityReport {
-  assertPositiveFinite(input.cssWidth, "cssWidth");
-  assertPositiveFinite(input.cssHeight, "cssHeight");
-  assertPositiveInteger(input.backingWidth, "backingWidth");
-  assertPositiveInteger(input.backingHeight, "backingHeight");
-  assertPositiveInteger(input.screenshotWidth, "screenshotWidth");
-  assertPositiveInteger(input.screenshotHeight, "screenshotHeight");
-  if (input.captureCssWidth !== undefined) assertPositiveFinite(input.captureCssWidth, "captureCssWidth");
-  if (input.captureCssHeight !== undefined) assertPositiveFinite(input.captureCssHeight, "captureCssHeight");
-  if (input.devicePixelRatio !== undefined) assertPositiveFinite(input.devicePixelRatio, "devicePixelRatio");
-  if (input.minimumEffectiveDpr !== undefined) assertPositiveFinite(input.minimumEffectiveDpr, "minimumEffectiveDpr");
-
-  const captureCssWidth = input.captureCssWidth ?? input.cssWidth;
-  const captureCssHeight = input.captureCssHeight ?? input.cssHeight;
-  const minimumEffectiveDpr = input.minimumEffectiveDpr ?? 1;
-  const effectiveBackingDprX = input.backingWidth / input.cssWidth;
-  const effectiveBackingDprY = input.backingHeight / input.cssHeight;
-  const effectiveCaptureDprX = input.screenshotWidth / captureCssWidth;
-  const effectiveCaptureDprY = input.screenshotHeight / captureCssHeight;
-  const captureToBackingScaleX = effectiveCaptureDprX / effectiveBackingDprX;
-  const captureToBackingScaleY = effectiveCaptureDprY / effectiveBackingDprY;
-  const capturesFullCanvas = nearlyEqual(captureCssWidth, input.cssWidth) && nearlyEqual(captureCssHeight, input.cssHeight);
-  const fullCanvasPixelMatch = capturesFullCanvas
-    && input.screenshotWidth === input.backingWidth
-    && input.screenshotHeight === input.backingHeight;
-  const captureDownsamplesCanvas = captureToBackingScaleX < 0.98 || captureToBackingScaleY < 0.98;
-  const captureUpscalesCanvas = captureToBackingScaleX > 1.02 || captureToBackingScaleY > 1.02;
-  const meetsMinimumEffectiveDpr = effectiveBackingDprX >= minimumEffectiveDpr && effectiveBackingDprY >= minimumEffectiveDpr;
-  const warnings = createCaptureQualityWarnings({
-    ...input,
-    captureCssWidth,
-    captureCssHeight,
-    minimumEffectiveDpr,
-    effectiveBackingDprX,
-    effectiveBackingDprY,
-    effectiveCaptureDprX,
-    effectiveCaptureDprY,
-    captureDownsamplesCanvas,
-    captureUpscalesCanvas,
-    fullCanvasPixelMatch,
-    capturesFullCanvas,
-    meetsMinimumEffectiveDpr
-  });
-
-  return {
-    status: warnings.length > 0 ? "partial" : "supported",
-    ...(input.label ? { label: input.label } : {}),
-    cssWidth: input.cssWidth,
-    cssHeight: input.cssHeight,
-    backingWidth: input.backingWidth,
-    backingHeight: input.backingHeight,
-    screenshotWidth: input.screenshotWidth,
-    screenshotHeight: input.screenshotHeight,
-    captureCssWidth,
-    captureCssHeight,
-    ...(input.devicePixelRatio !== undefined ? { devicePixelRatio: input.devicePixelRatio } : {}),
-    minimumEffectiveDpr,
-    effectiveBackingDprX: round(effectiveBackingDprX),
-    effectiveBackingDprY: round(effectiveBackingDprY),
-    effectiveCaptureDprX: round(effectiveCaptureDprX),
-    effectiveCaptureDprY: round(effectiveCaptureDprY),
-    captureToBackingScaleX: round(captureToBackingScaleX),
-    captureToBackingScaleY: round(captureToBackingScaleY),
-    capturesFullCanvas,
-    fullCanvasPixelMatch,
-    captureDownsamplesCanvas,
-    captureUpscalesCanvas,
-    meetsMinimumEffectiveDpr,
-    warnings
-  };
-}
-
-export function evaluateRendererFrameCadence(input: RendererFrameCadenceInput): RendererFrameCadenceReport {
-  const targetFrameMs = input.targetFrameMs ?? 16.667;
-  assertPositiveFinite(targetFrameMs, "targetFrameMs");
-  if (input.renderMs !== undefined) assertNonNegativeFinite(input.renderMs, "renderMs");
-  if (input.loopMs !== undefined) assertNonNegativeFinite(input.loopMs, "loopMs");
-  if (input.frameIntervalMs !== undefined) assertNonNegativeFinite(input.frameIntervalMs, "frameIntervalMs");
-  if (input.readbackMs !== undefined) assertNonNegativeFinite(input.readbackMs, "readbackMs");
-  if (input.screenshotCaptureOverheadMs !== undefined) assertNonNegativeFinite(input.screenshotCaptureOverheadMs, "screenshotCaptureOverheadMs");
-  if (input.sampleCount !== undefined) assertPositiveInteger(input.sampleCount, "sampleCount");
-
-  const renderBudgetRatio = input.renderMs !== undefined ? input.renderMs / targetFrameMs : undefined;
-  const loopBudgetRatio = input.loopMs !== undefined ? input.loopMs / targetFrameMs : undefined;
-  const frameIntervalBudgetRatio = input.frameIntervalMs !== undefined ? input.frameIntervalMs / targetFrameMs : undefined;
-  const readbackBudgetRatio = input.readbackMs !== undefined ? input.readbackMs / targetFrameMs : undefined;
-  const captureOverheadFrames = input.screenshotCaptureOverheadMs !== undefined ? input.screenshotCaptureOverheadMs / targetFrameMs : undefined;
-  const loopHeadroomMs = input.loopMs !== undefined ? targetFrameMs - input.loopMs : undefined;
-  const warnings = createFrameCadenceWarnings({
-    ...input,
-    targetFrameMs,
-    renderBudgetRatio,
-    loopBudgetRatio,
-    frameIntervalBudgetRatio,
-    readbackBudgetRatio,
-    captureOverheadFrames
-  });
-
-  return {
-    status: warnings.length > 0 ? "partial" : "supported",
-    targetFrameMs: round(targetFrameMs),
-    ...(input.renderMs !== undefined ? { renderMs: round(input.renderMs) } : {}),
-    ...(input.loopMs !== undefined ? { loopMs: round(input.loopMs) } : {}),
-    ...(input.frameIntervalMs !== undefined ? { frameIntervalMs: round(input.frameIntervalMs) } : {}),
-    ...(input.readbackMs !== undefined ? { readbackMs: round(input.readbackMs) } : {}),
-    ...(input.screenshotCaptureOverheadMs !== undefined ? { screenshotCaptureOverheadMs: round(input.screenshotCaptureOverheadMs) } : {}),
-    ...(input.sampleCount !== undefined ? { sampleCount: input.sampleCount } : {}),
-    ...(renderBudgetRatio !== undefined ? { renderBudgetRatio: round(renderBudgetRatio) } : {}),
-    ...(loopBudgetRatio !== undefined ? { loopBudgetRatio: round(loopBudgetRatio) } : {}),
-    ...(frameIntervalBudgetRatio !== undefined ? { frameIntervalBudgetRatio: round(frameIntervalBudgetRatio) } : {}),
-    ...(readbackBudgetRatio !== undefined ? { readbackBudgetRatio: round(readbackBudgetRatio) } : {}),
-    ...(captureOverheadFrames !== undefined ? { captureOverheadFrames: round(captureOverheadFrames) } : {}),
-    ...(loopHeadroomMs !== undefined ? { loopHeadroomMs: round(loopHeadroomMs) } : {}),
-    stableForCapture: warnings.length === 0,
-    warnings
-  };
-}
-
-function normalizePostprocess(
-  postprocess: RendererVisualPipelineReportOptions["postprocess"]
-): RendererVisualPostprocessDescriptor | undefined {
-  if (postprocess === undefined || postprocess === false) return undefined;
-  if (postprocess === true) return {};
-  return postprocess;
-}
-
-function collectPostprocessPassNames(postprocess: RendererVisualPostprocessDescriptor): readonly RendererVisualPostprocessPassName[] {
-  const passes: RendererVisualPostprocessPassName[] = [];
-  if (postprocess.bloom) passes.push("bloom");
-  if (postprocess.toneMapping !== false) passes.push("tone-mapping");
-  if (postprocess.colorGrade) passes.push("color-grade");
-  if (postprocess.chromaticAberration) passes.push("chromatic-aberration");
-  if (postprocess.filmGrain) passes.push("film-grain");
-  if (postprocess.depthOfField) passes.push("depth-of-field");
-  if (postprocess.motionBlur) passes.push("motion-blur");
-  if (postprocess.contactShadow) passes.push("contact-shadow");
-  if (postprocess.ssao) passes.push("ssao");
-  if (postprocess.ssr) passes.push("ssr");
-  if (postprocess.taa) passes.push("taa");
-  if (postprocess.outline) passes.push("outline");
-  if (postprocess.fxaa) passes.push("fxaa");
-  return passes;
-}
-
-function resolvePostprocessTargetFormat(
-  capabilities: ReadonlySet<RenderDeviceCapability>,
-  postprocess: RendererVisualPostprocessDescriptor
-): RendererVisualTargetFormat {
-  if (postprocess.targetFormat) return postprocess.targetFormat;
-  if (postprocess.toneMapping === false) return "rgba8";
-  return capabilities.has("hdr-render-targets") ? "rgba16f" : "rgba8";
-}
-
-function createHdrTargetReport(
-  capabilities: ReadonlySet<RenderDeviceCapability>,
-  targetFormat: RendererVisualTargetFormat,
-  toneMapping: ToneMappingOptions | false | undefined
-): RendererVisualHdrTargetReport {
-  const requested = HDR_FORMATS.includes(targetFormat);
-  const capabilityAdvertised = capabilities.has("hdr-render-targets");
-  const warnings: string[] = [];
-  if (requested && !capabilityAdvertised) {
-    warnings.push(`HDR postprocess target ${targetFormat} was requested, but the backend does not advertise hdr-render-targets.`);
-  }
-  if (requested && toneMapping === false) {
-    warnings.push(`HDR postprocess target ${targetFormat} requires tone mapping before RGBA8 presentation.`);
-  }
-
-  return {
-    status: warnings.length > 0 ? "unsupported" : "supported",
-    requested,
-    supportedByBackend: !requested || capabilityAdvertised,
-    capabilityAdvertised,
-    targetFormat,
-    ...(requested && !capabilityAdvertised ? { fallbackFormat: "rgba8" } : {}),
-    toneMappingRequired: requested,
-    warnings
-  };
-}
-
-function createToneMappingReport(
-  postprocess: RendererVisualPostprocessDescriptor | undefined,
-  targetFormat: RendererVisualTargetFormat
-): RendererVisualToneMappingReport {
-  const availablePresets = listExternalParityToneMappingPresets().map((preset) => preset.name);
-  if (!postprocess || postprocess.toneMapping === false) {
-    const warnings = HDR_FORMATS.includes(targetFormat)
-      ? [`HDR target ${targetFormat} cannot be presented honestly without tone mapping.`]
-      : [];
-    return {
-      status: warnings.length > 0 ? "unsupported" : "supported",
-      enabled: false,
-      availablePresets,
-      warnings
-    };
-  }
-
-  const options = postprocess.toneMapping ?? {};
-  const resolved = {
-    exposure: options.exposure ?? 1,
-    whitePoint: options.whitePoint ?? 1,
-    gamma: options.gamma ?? 2.2,
-    operator: options.operator ?? "reinhard",
-    inputColorSpace: options.inputColorSpace ?? "linear",
-    outputColorSpace: options.outputColorSpace ?? "srgb"
-  } satisfies Required<ToneMappingOptions>;
-  const warnings: string[] = [];
-  if (resolved.outputColorSpace !== "srgb") {
-    warnings.push(`Tone mapping outputColorSpace is ${resolved.outputColorSpace}; screenshot and browser presentation consistency is strongest with srgb.`);
-  }
-
-  return {
-    status: warnings.length > 0 ? "partial" : "supported",
-    enabled: true,
-    operator: resolved.operator,
-    exposure: resolved.exposure,
-    whitePoint: resolved.whitePoint,
-    gamma: resolved.gamma,
-    inputColorSpace: resolved.inputColorSpace,
-    outputColorSpace: resolved.outputColorSpace,
-    calibration: createToneMappingCalibration(resolved),
-    availablePresets,
-    warnings
-  };
-}
-
-function createPostprocessReport(options: {
-  readonly enabled: boolean;
-  readonly passNames: readonly RendererVisualPostprocessPassName[];
-  readonly targetFormat: RendererVisualTargetFormat;
-  readonly plan?: RendererPostprocessPlanDiagnostics;
-  readonly width: number;
-  readonly height: number;
-  readonly presentationColorSpace: A3DColorSpace;
-  readonly hdrTargetStatus: RendererVisualPipelineStatus;
-  readonly toneMappingStatus: RendererVisualPipelineStatus;
-}): RendererVisualPostprocessReport {
-  const warnings: string[] = [];
-  if (options.enabled && options.passNames.length === 0) {
-    warnings.push("Postprocess is enabled with no passes; renderer will copy/present the forward target without color changes.");
-  }
-  if (options.plan && options.plan.missingInputs.length > 0) {
-    warnings.push(`Postprocess plan is missing required inputs: ${options.plan.missingInputs.join(", ")}.`);
-  }
-  if (options.hdrTargetStatus === "unsupported" || options.toneMappingStatus === "unsupported") {
-    warnings.push("Postprocess plan is not executable as requested; renderer guards will reject unsupported HDR presentation.");
-  }
-  const executionMode = options.plan?.executionMode ?? "none";
-
-  return {
-    status: combineStatuses([
-      options.hdrTargetStatus,
-      options.toneMappingStatus,
-      warnings.length > 0 ? "partial" : "supported"
-    ]),
-    enabled: options.enabled,
-    passNames: options.passNames,
-    targetFormat: options.targetFormat,
-    sourceTargetFormat: options.plan?.sourceTargetFormat ?? options.targetFormat,
-    executionMode,
-    nativePresentation: executionMode === "renderer-owned-fused-ldr-native",
-    usesReadback: (options.plan?.readbackPassNames.length ?? 0) > 0,
-    missingInputs: options.plan?.missingInputs ?? [],
-    readbackPassNames: options.plan?.readbackPassNames ?? [],
-    rendererOwnedPassNames: options.plan?.rendererOwnedPassNames ?? [],
-    clarityWarnings: options.plan?.clarityWarnings ?? [],
-    forwardOutputColorSpace: options.enabled ? "linear" : "srgb",
-    presentationColorSpace: options.presentationColorSpace,
-    renderTargetWidth: options.width,
-    renderTargetHeight: options.height,
-    ...(options.plan ? { plan: options.plan } : {}),
-    warnings
-  };
-}
-
-function combineStatuses(statuses: readonly (RendererVisualPipelineStatus | undefined)[]): RendererVisualPipelineStatus {
-  if (statuses.includes("unsupported")) return "unsupported";
-  if (statuses.includes("partial")) return "partial";
-  return "supported";
-}
-
-function createCanvasBackingWarnings(
-  input: RendererCanvasBackingInput,
-  expectedWidth: number,
-  expectedHeight: number,
-  hasActualDimensions: boolean,
-  matches: boolean
-): readonly string[] {
-  if (!hasActualDimensions) {
-    return [`Canvas backing store dimensions were not provided; expected ${expectedWidth}x${expectedHeight} for CSS ${input.cssWidth}x${input.cssHeight} at DPR ${input.devicePixelRatio}.`];
-  }
-  if (!matches) {
-    return [`Canvas backing store ${input.actualWidth}x${input.actualHeight} does not match CSS ${input.cssWidth}x${input.cssHeight} at DPR ${input.devicePixelRatio}; expected ${expectedWidth}x${expectedHeight}.`];
-  }
-  return [];
-}
-
-function createCaptureQualityWarnings(input: RendererCaptureQualityInput & {
-  readonly captureCssWidth: number;
-  readonly captureCssHeight: number;
-  readonly minimumEffectiveDpr: number;
-  readonly effectiveBackingDprX: number;
-  readonly effectiveBackingDprY: number;
-  readonly effectiveCaptureDprX: number;
-  readonly effectiveCaptureDprY: number;
-  readonly captureDownsamplesCanvas: boolean;
-  readonly captureUpscalesCanvas: boolean;
-  readonly fullCanvasPixelMatch: boolean;
-  readonly capturesFullCanvas: boolean;
-  readonly meetsMinimumEffectiveDpr: boolean;
-}): readonly string[] {
-  const warnings: string[] = [];
-  if (!input.meetsMinimumEffectiveDpr) {
-    warnings.push(`Canvas backing DPR ${round(input.effectiveBackingDprX)}x${round(input.effectiveBackingDprY)} is below the requested minimum ${input.minimumEffectiveDpr}.`);
-  }
-  if (input.devicePixelRatio !== undefined && (input.effectiveBackingDprX < input.devicePixelRatio * 0.98 || input.effectiveBackingDprY < input.devicePixelRatio * 0.98)) {
-    warnings.push(`Canvas backing DPR ${round(input.effectiveBackingDprX)}x${round(input.effectiveBackingDprY)} is below devicePixelRatio ${input.devicePixelRatio}; a max-edge clamp or resize mismatch may be reducing effective capture detail.`);
-  }
-  if (input.captureDownsamplesCanvas) {
-    warnings.push(`Screenshot capture DPR ${round(input.effectiveCaptureDprX)}x${round(input.effectiveCaptureDprY)} is below canvas backing DPR ${round(input.effectiveBackingDprX)}x${round(input.effectiveBackingDprY)}; browser capture is downsampling renderer detail.`);
-  }
-  if (input.captureUpscalesCanvas) {
-    warnings.push(`Screenshot capture DPR ${round(input.effectiveCaptureDprX)}x${round(input.effectiveCaptureDprY)} is above canvas backing DPR ${round(input.effectiveBackingDprX)}x${round(input.effectiveBackingDprY)}; screenshot pixels may be upscaled from renderer output.`);
-  }
-  if (input.capturesFullCanvas && !input.fullCanvasPixelMatch) {
-    warnings.push(`Full-canvas screenshot ${input.screenshotWidth}x${input.screenshotHeight} does not match canvas backing ${input.backingWidth}x${input.backingHeight}.`);
-  }
-  return warnings;
-}
-
-function createFrameCadenceWarnings(input: RendererFrameCadenceInput & {
-  readonly targetFrameMs: number;
-  readonly renderBudgetRatio?: number;
-  readonly loopBudgetRatio?: number;
-  readonly frameIntervalBudgetRatio?: number;
-  readonly readbackBudgetRatio?: number;
-  readonly captureOverheadFrames?: number;
-}): readonly string[] {
-  const warnings: string[] = [];
-  if (input.renderBudgetRatio !== undefined && input.renderBudgetRatio > 1) {
-    warnings.push(`Render work ${round(input.renderBudgetRatio)}x exceeds the ${round(input.targetFrameMs)}ms frame budget.`);
-  }
-  if (input.loopBudgetRatio !== undefined && input.loopBudgetRatio > 1) {
-    warnings.push(`Total loop work ${round(input.loopBudgetRatio)}x exceeds the ${round(input.targetFrameMs)}ms frame budget.`);
-  }
-  if (input.frameIntervalBudgetRatio !== undefined && input.frameIntervalBudgetRatio > 1.25) {
-    warnings.push(`Observed frame interval ${round(input.frameIntervalBudgetRatio)}x exceeds the target cadence; capture may land on a stalled frame.`);
-  }
-  if (input.readbackBudgetRatio !== undefined && input.readbackBudgetRatio > 0.5) {
-    warnings.push(`Readback cost ${round(input.readbackBudgetRatio)}x of the frame budget can affect capture cadence.`);
-  }
-  if (input.captureOverheadFrames !== undefined && input.captureOverheadFrames > 1) {
-    warnings.push(`Screenshot capture overhead spans ${round(input.captureOverheadFrames)} frame budgets; visual review captures may include stall artifacts.`);
-  }
-  return warnings;
-}
-
-function assertPositiveInteger(value: number, name: string): void {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new Error(`${name} must be a positive integer.`);
-  }
-}
-
-function assertNonNegativeFinite(value: number, name: string): void {
-  if (!Number.isFinite(value) || value < 0) {
-    throw new Error(`${name} must be a finite non-negative number.`);
-  }
-}
-
-function assertPositiveFinite(value: number, name: string): void {
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`${name} must be a finite positive number.`);
-  }
-}
-
-function nearlyEqual(left: number, right: number): boolean {
-  return Math.abs(left - right) <= 0.001;
-}
-
-function round(value: number): number {
-  return Number(value.toFixed(4));
-}